From 3426a6648af8791e39ed4e8cb84c46b32b139bb8 Mon Sep 17 00:00:00 2001 From: Luka Peschke Date: Thu, 21 Nov 2019 17:01:17 +0100 Subject: [PATCH] Build docs with -W This fixes all build warnings in the docs, and makes them build with -W (consider warnings as errors). Work items: * Remove the useless "METRICS_CONF" global variable in the monasca collector. It was causing the "load_conf()" function to fail, as the /etc/cloudkitty/metrics.yml file couldn't be found. * Change the docstring indentation in cloudkitty/rating/hash/controllers/mapping.py. This was the cause for the "doc/source/api-reference/v1/rating/hashmap.rst:12: WARNING: Field list ends without a blank line; unexpected unindent." message. * Added a cloudkitty.conf sample to the admin documentation. * Deleted unused files. * Fixed the policy.yaml sample include path. * Sorted the v2 API parameters alphabetically. * Ignored the "wsmeext.sphinxext: directive 'autoattribute' is already registered" warning * Added :noindex: directives to functions documented twice. * Made sphinx always build with -W. Change-Id: I5f1ab04e18920f3352c2807878cad327692a225f --- cloudkitty/collector/monasca.py | 2 - cloudkitty/rating/hash/controllers/mapping.py | 3 +- cloudkitty/rating/hash/controllers/root.py | 4 +- doc/source/_static/cloudkitty.conf.sample | 1387 +++++++++++++++++ .../admin/configuration/configuration.rst | 3 + doc/source/admin/configuration/index.rst | 1 + .../configuration/samples/cloudkitty-conf.rst | 5 + .../admin/configuration/samples/index.rst | 11 - .../configuration/samples/policy-yaml.rst | 4 +- doc/source/admin/sample_policy.rst | 16 - .../v2/dataframes/dataframes_parameters.yml | 70 +- .../v2/scope/scope_parameters.yml | 82 +- .../v2/summary/summary_parameters.yml | 52 +- doc/source/conf.py | 8 +- doc/source/developer/api/tutorial.rst | 4 + doc/source/pdf-index.rst | 2 + tox.ini | 4 +- 17 files changed, 1519 insertions(+), 139 deletions(-) create mode 100644 doc/source/_static/cloudkitty.conf.sample create mode 100644 doc/source/admin/configuration/samples/cloudkitty-conf.rst delete mode 100644 doc/source/admin/configuration/samples/index.rst delete mode 100644 doc/source/admin/sample_policy.rst diff --git a/cloudkitty/collector/monasca.py b/cloudkitty/collector/monasca.py index 41fbca97..586f31e9 100644 --- a/cloudkitty/collector/monasca.py +++ b/cloudkitty/collector/monasca.py @@ -53,8 +53,6 @@ CONF.register_opts(collector_monasca_opts, COLLECTOR_MONASCA_OPTS) ks_loading.register_auth_conf_options(CONF, COLLECTOR_MONASCA_OPTS) ks_loading.register_session_conf_options(CONF, COLLECTOR_MONASCA_OPTS) -METRICS_CONF = ck_utils.load_conf(CONF.collect.metrics_conf) - MONASCA_EXTRA_SCHEMA = { Required('extra_args', default={}): { # Key corresponding to the resource id in a metric's dimensions diff --git a/cloudkitty/rating/hash/controllers/mapping.py b/cloudkitty/rating/hash/controllers/mapping.py index 4e57cfb6..9b75658f 100644 --- a/cloudkitty/rating/hash/controllers/mapping.py +++ b/cloudkitty/rating/hash/controllers/mapping.py @@ -70,7 +70,8 @@ class HashMapMappingsController(rating.RatingRestControllerBase): :param no_group: Filter on orphaned mappings. :param tenant_id: Tenant UUID to filter on. :param filter_tenant: Explicitly filter on tenant (default is to not - filter on tenant). Useful if you want to filter on tenant being None. + filter on tenant). Useful if you want to filter + on tenant being None. :return: List of every mappings. """ hashmap = db_api.get_instance() diff --git a/cloudkitty/rating/hash/controllers/root.py b/cloudkitty/rating/hash/controllers/root.py index 8bbaec89..48ebc333 100644 --- a/cloudkitty/rating/hash/controllers/root.py +++ b/cloudkitty/rating/hash/controllers/root.py @@ -26,9 +26,7 @@ from cloudkitty.rating.hash.datamodels import mapping as mapping_models class HashMapConfigController(rating.RatingRestControllerBase): - """Controller exposing all management sub controllers. - - """ + """Controller exposing all management sub controllers.""" _custom_actions = { 'types': ['GET'] diff --git a/doc/source/_static/cloudkitty.conf.sample b/doc/source/_static/cloudkitty.conf.sample new file mode 100644 index 00000000..8c0a67c8 --- /dev/null +++ b/doc/source/_static/cloudkitty.conf.sample @@ -0,0 +1,1387 @@ +[DEFAULT] + +# +# From cloudkitty.common.config +# + +# Configuration file for WSGI definition of API. (string value) +#api_paste_config = api_paste.ini + +# The strategy to use for auth. Supports noauth and keystone (string +# value) +# Possible values: +# noauth - +# keystone - +#auth_strategy = keystone + +# Name of this node. This can be an opaque identifier. It is not +# necessarily a hostname, FQDN, or IP address. However, the node name +# must be valid within an AMQP key. (string value) +# +# This option has a sample default set, which means that +# its actual default value may vary from the one documented +# below. +#host = + +# +# From oslo.log +# + +# If set to true, the logging level will be set to DEBUG instead of +# the default INFO level. (boolean value) +# Note: This option can be changed without restarting. +#debug = false + +# The name of a logging configuration file. This file is appended to +# any existing logging configuration files. For details about logging +# configuration files, see the Python logging module documentation. +# Note that when logging configuration files are used then all logging +# configuration is set in the configuration file and other logging +# configuration options are ignored (for example, log-date-format). +# (string value) +# Note: This option can be changed without restarting. +# Deprecated group/name - [DEFAULT]/log_config +#log_config_append = + +# Defines the format string for %%(asctime)s in log records. Default: +# %(default)s . This option is ignored if log_config_append is set. +# (string value) +#log_date_format = %Y-%m-%d %H:%M:%S + +# (Optional) Name of log file to send logging output to. If no default +# is set, logging will go to stderr as defined by use_stderr. This +# option is ignored if log_config_append is set. (string value) +# Deprecated group/name - [DEFAULT]/logfile +#log_file = + +# (Optional) The base directory used for relative log_file paths. +# This option is ignored if log_config_append is set. (string value) +# Deprecated group/name - [DEFAULT]/logdir +#log_dir = + +# Uses logging handler designed to watch file system. When log file is +# moved or removed this handler will open a new log file with +# specified path instantaneously. It makes sense only if log_file +# option is specified and Linux platform is used. This option is +# ignored if log_config_append is set. (boolean value) +#watch_log_file = false + +# Use syslog for logging. Existing syslog format is DEPRECATED and +# will be changed later to honor RFC5424. This option is ignored if +# log_config_append is set. (boolean value) +#use_syslog = false + +# Enable journald for logging. If running in a systemd environment you +# may wish to enable journal support. Doing so will use the journal +# native protocol which includes structured metadata in addition to +# log messages.This option is ignored if log_config_append is set. +# (boolean value) +#use_journal = false + +# Syslog facility to receive log lines. This option is ignored if +# log_config_append is set. (string value) +#syslog_log_facility = LOG_USER + +# Use JSON formatting for logging. This option is ignored if +# log_config_append is set. (boolean value) +#use_json = false + +# Log output to standard error. This option is ignored if +# log_config_append is set. (boolean value) +#use_stderr = false + +# Log output to Windows Event Log. (boolean value) +#use_eventlog = false + +# The amount of time before the log files are rotated. This option is +# ignored unless log_rotation_type is setto "interval". (integer +# value) +#log_rotate_interval = 1 + +# Rotation interval type. The time of the last file change (or the +# time when the service was started) is used when scheduling the next +# rotation. (string value) +# Possible values: +# Seconds - +# Minutes - +# Hours - +# Days - +# Weekday - +# Midnight - +#log_rotate_interval_type = days + +# Maximum number of rotated log files. (integer value) +#max_logfile_count = 30 + +# Log file maximum size in MB. This option is ignored if +# "log_rotation_type" is not set to "size". (integer value) +#max_logfile_size_mb = 200 + +# Log rotation type. (string value) +# Possible values: +# interval - Rotate logs at predefined time intervals. +# size - Rotate logs once they reach a predefined size. +# none - Do not rotate log files. +#log_rotation_type = none + +# Format string to use for log messages with context. Used by +# oslo_log.formatters.ContextFormatter (string value) +#logging_context_format_string = %(asctime)s.%(msecs)03d %(process)d %(levelname)s %(name)s [%(request_id)s %(user_identity)s] %(instance)s%(message)s + +# Format string to use for log messages when context is undefined. +# Used by oslo_log.formatters.ContextFormatter (string value) +#logging_default_format_string = %(asctime)s.%(msecs)03d %(process)d %(levelname)s %(name)s [-] %(instance)s%(message)s + +# Additional data to append to log message when logging level for the +# message is DEBUG. Used by oslo_log.formatters.ContextFormatter +# (string value) +#logging_debug_format_suffix = %(funcName)s %(pathname)s:%(lineno)d + +# Prefix each line of exception output with this format. Used by +# oslo_log.formatters.ContextFormatter (string value) +#logging_exception_prefix = %(asctime)s.%(msecs)03d %(process)d ERROR %(name)s %(instance)s + +# Defines the format string for %(user_identity)s that is used in +# logging_context_format_string. Used by +# oslo_log.formatters.ContextFormatter (string value) +#logging_user_identity_format = %(user)s %(tenant)s %(domain)s %(user_domain)s %(project_domain)s + +# List of package logging levels in logger=LEVEL pairs. This option is +# ignored if log_config_append is set. (list value) +#default_log_levels = amqp=WARN,amqplib=WARN,boto=WARN,qpid=WARN,sqlalchemy=WARN,suds=INFO,oslo.messaging=INFO,oslo_messaging=INFO,iso8601=WARN,requests.packages.urllib3.connectionpool=WARN,urllib3.connectionpool=WARN,websocket=WARN,requests.packages.urllib3.util.retry=WARN,urllib3.util.retry=WARN,keystonemiddleware=WARN,routes.middleware=WARN,stevedore=WARN,taskflow=WARN,keystoneauth=WARN,oslo.cache=INFO,oslo_policy=INFO,dogpile.core.dogpile=INFO + +# Enables or disables publication of error events. (boolean value) +#publish_errors = false + +# The format for an instance that is passed with the log message. +# (string value) +#instance_format = "[instance: %(uuid)s] " + +# The format for an instance UUID that is passed with the log message. +# (string value) +#instance_uuid_format = "[instance: %(uuid)s] " + +# Interval, number of seconds, of log rate limiting. (integer value) +#rate_limit_interval = 0 + +# Maximum number of logged messages per rate_limit_interval. (integer +# value) +#rate_limit_burst = 0 + +# Log level name used by rate limiting: CRITICAL, ERROR, INFO, +# WARNING, DEBUG or empty string. Logs with level greater or equal to +# rate_limit_except_level are not filtered. An empty string means that +# all levels are filtered. (string value) +#rate_limit_except_level = CRITICAL + +# Enables or disables fatal status of deprecations. (boolean value) +#fatal_deprecations = false + +# +# From oslo.messaging +# + +# Size of RPC connection pool. (integer value) +#rpc_conn_pool_size = 30 + +# The pool size limit for connections expiration policy (integer +# value) +#conn_pool_min_size = 2 + +# The time-to-live in sec of idle connections in the pool (integer +# value) +#conn_pool_ttl = 1200 + +# Size of executor thread pool when executor is threading or eventlet. +# (integer value) +# Deprecated group/name - [DEFAULT]/rpc_thread_pool_size +#executor_thread_pool_size = 64 + +# Seconds to wait for a response from a call. (integer value) +#rpc_response_timeout = 60 + +# The network address and optional user credentials for connecting to +# the messaging backend, in URL format. The expected format is: +# +# driver://[user:pass@]host:port[,[userN:passN@]hostN:portN]/virtual_host?query +# +# Example: rabbit://rabbitmq:password@127.0.0.1:5672// +# +# For full details on the fields in the URL see the documentation of +# oslo_messaging.TransportURL at +# https://docs.openstack.org/oslo.messaging/latest/reference/transport.html +# (string value) +#transport_url = rabbit:// + +# The default exchange under which topics are scoped. May be +# overridden by an exchange name specified in the transport_url +# option. (string value) +#control_exchange = openstack + + +[api] + +# +# From cloudkitty.common.config +# + +# The port for the cloudkitty API server. (port value) +# Minimum value: 0 +# Maximum value: 65535 +#port = 8889 + + +[collect] + +# +# From cloudkitty.common.config +# + +# Data collector. (string value) +#collector = gnocchi + +# Rating period in seconds. (integer value) +#period = 3600 + +# Wait for N periods before collecting new data. (integer value) +#wait_periods = 2 + +# Metrology configuration file. (string value) +#metrics_conf = /etc/cloudkitty/metrics.yml + +# Key defining a scope. project_id or domain_id for OpenStack, but can +# be anything. (string value) +#scope_key = project_id + + +[collector_gnocchi] + +# +# From cloudkitty.common.config +# + +# Gnocchi auth type (keystone or basic). Keystone credentials can be +# specified through the "auth_section" parameter (string value) +# Possible values: +# keystone - +# basic - +#gnocchi_auth_type = keystone + +# Gnocchi user (for basic auth only) (string value) +#gnocchi_user = + +# Gnocchi endpoint (for basic auth only) (string value) +#gnocchi_endpoint = + +# Endpoint URL type (for keystone auth only) (string value) +#interface = internalURL + +# Region Name (string value) +#region_name = RegionOne + + +[collector_monasca] + +# +# From cloudkitty.common.config +# + +# Endpoint URL type (defaults to internal) (string value) +#interface = internal + +# Name of the Monasca service (defaults to monasca) (string value) +#monasca_service_name = monasca + + +[collector_prometheus] + +# +# From cloudkitty.common.config +# + +# Prometheus service URL (string value) +#prometheus_url = + +# Prometheus user (for basic auth only) (string value) +#prometheus_user = + +# Prometheus user password (for basic auth only) (string value) +#prometheus_password = + +# Custom certificate authority file path (string value) +#cafile = + +# Explicitly trust untrusted HTTPS responses (boolean value) +#insecure = false + + +[cors] + +# +# From oslo.middleware.cors +# + +# Indicate whether this resource may be shared with the domain +# received in the requests "origin" header. Format: +# "://[:]", no trailing slash. Example: +# https://horizon.example.com (list value) +#allowed_origin = + +# Indicate that the actual request can include user credentials +# (boolean value) +#allow_credentials = true + +# Indicate which headers are safe to expose to the API. Defaults to +# HTTP Simple Headers. (list value) +#expose_headers = X-Auth-Token,X-Subject-Token,X-Service-Token,X-OpenStack-Request-ID + +# Maximum cache age of CORS preflight requests. (integer value) +#max_age = 3600 + +# Indicate which methods can be used during the actual request. (list +# value) +#allow_methods = GET,PUT,POST,DELETE,PATCH + +# Indicate which header field names may be used during the actual +# request. (list value) +#allow_headers = X-Auth-Token,X-Subject-Token,X-Roles,X-User-Id,X-Domain-Id,X-Project-Id,X-Tenant-Id,X-OpenStack-Request-ID + + +[database] + +# +# From oslo.db +# + +# If True, SQLite uses synchronous mode. (boolean value) +#sqlite_synchronous = true + +# The back end to use for the database. (string value) +# Deprecated group/name - [DEFAULT]/db_backend +#backend = sqlalchemy + +# The SQLAlchemy connection string to use to connect to the database. +# (string value) +# Deprecated group/name - [DEFAULT]/sql_connection +# Deprecated group/name - [DATABASE]/sql_connection +# Deprecated group/name - [sql]/connection +#connection = + +# The SQLAlchemy connection string to use to connect to the slave +# database. (string value) +#slave_connection = + +# The SQL mode to be used for MySQL sessions. This option, including +# the default, overrides any server-set SQL mode. To use whatever SQL +# mode is set by the server configuration, set this to no value. +# Example: mysql_sql_mode= (string value) +#mysql_sql_mode = TRADITIONAL + +# If True, transparently enables support for handling MySQL Cluster +# (NDB). (boolean value) +#mysql_enable_ndb = false + +# Connections which have been present in the connection pool longer +# than this number of seconds will be replaced with a new one the next +# time they are checked out from the pool. (integer value) +# Deprecated group/name - [DATABASE]/idle_timeout +# Deprecated group/name - [database]/idle_timeout +# Deprecated group/name - [DEFAULT]/sql_idle_timeout +# Deprecated group/name - [DATABASE]/sql_idle_timeout +# Deprecated group/name - [sql]/idle_timeout +#connection_recycle_time = 3600 + +# Maximum number of SQL connections to keep open in a pool. Setting a +# value of 0 indicates no limit. (integer value) +# Deprecated group/name - [DEFAULT]/sql_max_pool_size +# Deprecated group/name - [DATABASE]/sql_max_pool_size +#max_pool_size = 5 + +# Maximum number of database connection retries during startup. Set to +# -1 to specify an infinite retry count. (integer value) +# Deprecated group/name - [DEFAULT]/sql_max_retries +# Deprecated group/name - [DATABASE]/sql_max_retries +#max_retries = 10 + +# Interval between retries of opening a SQL connection. (integer +# value) +# Deprecated group/name - [DEFAULT]/sql_retry_interval +# Deprecated group/name - [DATABASE]/reconnect_interval +#retry_interval = 10 + +# If set, use this value for max_overflow with SQLAlchemy. (integer +# value) +# Deprecated group/name - [DEFAULT]/sql_max_overflow +# Deprecated group/name - [DATABASE]/sqlalchemy_max_overflow +#max_overflow = 50 + +# Verbosity of SQL debugging information: 0=None, 100=Everything. +# (integer value) +# Minimum value: 0 +# Maximum value: 100 +# Deprecated group/name - [DEFAULT]/sql_connection_debug +#connection_debug = 0 + +# Add Python stack traces to SQL as comment strings. (boolean value) +# Deprecated group/name - [DEFAULT]/sql_connection_trace +#connection_trace = false + +# If set, use this value for pool_timeout with SQLAlchemy. (integer +# value) +# Deprecated group/name - [DATABASE]/sqlalchemy_pool_timeout +#pool_timeout = + +# Enable the experimental use of database reconnect on connection +# lost. (boolean value) +#use_db_reconnect = false + +# Seconds between retries of a database transaction. (integer value) +#db_retry_interval = 1 + +# If True, increases the interval between retries of a database +# operation up to db_max_retry_interval. (boolean value) +#db_inc_retry_interval = true + +# If db_inc_retry_interval is set, the maximum seconds between retries +# of a database operation. (integer value) +#db_max_retry_interval = 10 + +# Maximum retries in case of connection error or deadlock error before +# error is raised. Set to -1 to specify an infinite retry count. +# (integer value) +#db_max_retries = 20 + +# Optional URL parameters to append onto the connection URL at connect +# time; specify as param1=value1¶m2=value2&... (string value) +#connection_parameters = + + +[fetcher] + +# +# From cloudkitty.common.config +# + +# Driver used to fetch the list of scopes to rate. (string value) +#backend = keystone + + +[fetcher_gnocchi] + +# +# From cloudkitty.common.config +# + +# Attribute from which scope_ids should be collected. (string value) +#scope_attribute = project_id + +# List of gnocchi resource types. All if left blank (list value) +#resource_types = generic + +# Gnocchi auth type (keystone or basic). Keystone credentials can be +# specified through the "auth_section" parameter (string value) +# Possible values: +# keystone - +# basic - +#gnocchi_auth_type = keystone + +# Gnocchi user (for basic auth only) (string value) +#gnocchi_user = + +# Gnocchi endpoint (for basic auth only) (string value) +#gnocchi_endpoint = + +# Endpoint URL type (for keystone auth only) (string value) +#interface = internalURL + +# Region Name (string value) +#region_name = RegionOne + +# Authentication type to load (string value) +# Deprecated group/name - [fetcher_gnocchi]/auth_plugin +#auth_type = + +# Config Section from which to load plugin specific options (string +# value) +#auth_section = + + +[fetcher_keystone] + +# +# From cloudkitty.common.config +# + +# Keystone version to use. (string value) +#keystone_version = 2 + + +[fetcher_prometheus] + +# +# From cloudkitty.common.config +# + +# Metric from which scope_ids should be requested (string value) +#metric = + +# Attribute from which scope_ids should be collected (string value) +#scope_attribute = project_id + +# Prometheus service URL (string value) +#prometheus_url = + +# Prometheus user (for basic auth only) (string value) +#prometheus_user = + +# Prometheus user (for basic auth only) (string value) +#prometheus_password = + +# Custom certificate authority file path (string value) +#cafile = + +# Explicitly trust untrusted HTTPS responses (boolean value) +#insecure = false + +# Metadata to filter out the scope_ids discovery request response +# (dict value) +#filters = + + +[fetcher_source] + +# +# From cloudkitty.common.config +# + +# list of source identifiers (list value) +#sources = + + +[keystone_authtoken] + +# +# From keystonemiddleware.auth_token +# + +# Complete "public" Identity API endpoint. This endpoint should not be +# an "admin" endpoint, as it should be accessible by all end users. +# Unauthenticated clients are redirected to this endpoint to +# authenticate. Although this endpoint should ideally be unversioned, +# client support in the wild varies. If you're using a versioned v2 +# endpoint here, then this should *not* be the same endpoint the +# service user utilizes for validating tokens, because normal end +# users may not be able to reach that endpoint. (string value) +# Deprecated group/name - [keystone_authtoken]/auth_uri +#www_authenticate_uri = + +# DEPRECATED: Complete "public" Identity API endpoint. This endpoint +# should not be an "admin" endpoint, as it should be accessible by all +# end users. Unauthenticated clients are redirected to this endpoint +# to authenticate. Although this endpoint should ideally be +# unversioned, client support in the wild varies. If you're using a +# versioned v2 endpoint here, then this should *not* be the same +# endpoint the service user utilizes for validating tokens, because +# normal end users may not be able to reach that endpoint. This option +# is deprecated in favor of www_authenticate_uri and will be removed +# in the S release. (string value) +# This option is deprecated for removal since Queens. +# Its value may be silently ignored in the future. +# Reason: The auth_uri option is deprecated in favor of +# www_authenticate_uri and will be removed in the S release. +#auth_uri = + +# API version of the Identity API endpoint. (string value) +#auth_version = + +# Interface to use for the Identity API endpoint. Valid values are +# "public", "internal" or "admin"(default). (string value) +#interface = admin + +# Do not handle authorization requests within the middleware, but +# delegate the authorization decision to downstream WSGI components. +# (boolean value) +#delay_auth_decision = false + +# Request timeout value for communicating with Identity API server. +# (integer value) +#http_connect_timeout = + +# How many times are we trying to reconnect when communicating with +# Identity API Server. (integer value) +#http_request_max_retries = 3 + +# Request environment key where the Swift cache object is stored. When +# auth_token middleware is deployed with a Swift cache, use this +# option to have the middleware share a caching backend with swift. +# Otherwise, use the ``memcached_servers`` option instead. (string +# value) +#cache = + +# Required if identity server requires client certificate (string +# value) +#certfile = + +# Required if identity server requires client certificate (string +# value) +#keyfile = + +# A PEM encoded Certificate Authority to use when verifying HTTPs +# connections. Defaults to system CAs. (string value) +#cafile = + +# Verify HTTPS connections. (boolean value) +#insecure = false + +# The region in which the identity server can be found. (string value) +#region_name = + +# Optionally specify a list of memcached server(s) to use for caching. +# If left undefined, tokens will instead be cached in-process. (list +# value) +# Deprecated group/name - [keystone_authtoken]/memcache_servers +#memcached_servers = + +# In order to prevent excessive effort spent validating tokens, the +# middleware caches previously-seen tokens for a configurable duration +# (in seconds). Set to -1 to disable caching completely. (integer +# value) +#token_cache_time = 300 + +# (Optional) If defined, indicate whether token data should be +# authenticated or authenticated and encrypted. If MAC, token data is +# authenticated (with HMAC) in the cache. If ENCRYPT, token data is +# encrypted and authenticated in the cache. If the value is not one of +# these options or empty, auth_token will raise an exception on +# initialization. (string value) +# Possible values: +# None - +# MAC - +# ENCRYPT - +#memcache_security_strategy = None + +# (Optional, mandatory if memcache_security_strategy is defined) This +# string is used for key derivation. (string value) +#memcache_secret_key = + +# (Optional) Number of seconds memcached server is considered dead +# before it is tried again. (integer value) +#memcache_pool_dead_retry = 300 + +# (Optional) Maximum total number of open connections to every +# memcached server. (integer value) +#memcache_pool_maxsize = 10 + +# (Optional) Socket timeout in seconds for communicating with a +# memcached server. (integer value) +#memcache_pool_socket_timeout = 3 + +# (Optional) Number of seconds a connection to memcached is held +# unused in the pool before it is closed. (integer value) +#memcache_pool_unused_timeout = 60 + +# (Optional) Number of seconds that an operation will wait to get a +# memcached client connection from the pool. (integer value) +#memcache_pool_conn_get_timeout = 10 + +# (Optional) Use the advanced (eventlet safe) memcached client pool. +# The advanced pool will only work under python 2.x. (boolean value) +#memcache_use_advanced_pool = false + +# (Optional) Indicate whether to set the X-Service-Catalog header. If +# False, middleware will not ask for service catalog on token +# validation and will not set the X-Service-Catalog header. (boolean +# value) +#include_service_catalog = true + +# Used to control the use and type of token binding. Can be set to: +# "disabled" to not check token binding. "permissive" (default) to +# validate binding information if the bind type is of a form known to +# the server and ignore it if not. "strict" like "permissive" but if +# the bind type is unknown the token will be rejected. "required" any +# form of token binding is needed to be allowed. Finally the name of a +# binding method that must be present in tokens. (string value) +#enforce_token_bind = permissive + +# A choice of roles that must be present in a service token. Service +# tokens are allowed to request that an expired token can be used and +# so this check should tightly control that only actual services +# should be sending this token. Roles here are applied as an ANY check +# so any role in this list must be present. For backwards +# compatibility reasons this currently only affects the allow_expired +# check. (list value) +#service_token_roles = service + +# For backwards compatibility reasons we must let valid service tokens +# pass that don't pass the service_token_roles check as valid. Setting +# this true will become the default in a future release and should be +# enabled if possible. (boolean value) +#service_token_roles_required = false + +# The name or type of the service as it appears in the service +# catalog. This is used to validate tokens that have restricted access +# rules. (string value) +#service_type = + +# Authentication type to load (string value) +# Deprecated group/name - [keystone_authtoken]/auth_plugin +#auth_type = + +# Config Section from which to load plugin specific options (string +# value) +#auth_section = + + +[orchestrator] + +# +# From cloudkitty.common.config +# + +# Coordination driver URL (string value) +#coordination_url = file:///var/lib/cloudkitty/locks + +# Max nb of workers to run. Defaults to the nb of available CPUs +# (integer value) +# Minimum value: 1 +# +# This option has a sample default set, which means that +# its actual default value may vary from the one documented +# below. +#max_workers = 4 + +# Maximal number of threads to use per worker. Defaults to 5 times the +# nb of available CPUs (integer value) +# Minimum value: 1 +# Deprecated group/name - [orchestrator]/max_greenthreads +# Advanced Option: intended for advanced users and not used +# by the majority of users, and might have a significant +# effect on stability and/or performance. +# +# This option has a sample default set, which means that +# its actual default value may vary from the one documented +# below. +#max_threads = 20 + + +[oslo_concurrency] + +# +# From oslo.concurrency +# + +# Enables or disables inter-process locks. (boolean value) +#disable_process_locking = false + +# Directory to use for lock files. For security, the specified +# directory should only be writable by the user running the processes +# that need locking. Defaults to environment variable OSLO_LOCK_PATH. +# If external locks are used, a lock path must be set. (string value) +#lock_path = + + +[oslo_messaging_amqp] + +# +# From oslo.messaging +# + +# Name for the AMQP container. must be globally unique. Defaults to a +# generated UUID (string value) +#container_name = + +# Timeout for inactive connections (in seconds) (integer value) +#idle_timeout = 0 + +# Debug: dump AMQP frames to stdout (boolean value) +#trace = false + +# Attempt to connect via SSL. If no other ssl-related parameters are +# given, it will use the system's CA-bundle to verify the server's +# certificate. (boolean value) +#ssl = false + +# CA certificate PEM file used to verify the server's certificate +# (string value) +#ssl_ca_file = + +# Self-identifying certificate PEM file for client authentication +# (string value) +#ssl_cert_file = + +# Private key PEM file used to sign ssl_cert_file certificate +# (optional) (string value) +#ssl_key_file = + +# Password for decrypting ssl_key_file (if encrypted) (string value) +#ssl_key_password = + +# By default SSL checks that the name in the server's certificate +# matches the hostname in the transport_url. In some configurations it +# may be preferable to use the virtual hostname instead, for example +# if the server uses the Server Name Indication TLS extension +# (rfc6066) to provide a certificate per virtual host. Set +# ssl_verify_vhost to True if the server's SSL certificate uses the +# virtual host name instead of the DNS name. (boolean value) +#ssl_verify_vhost = false + +# Space separated list of acceptable SASL mechanisms (string value) +#sasl_mechanisms = + +# Path to directory that contains the SASL configuration (string +# value) +#sasl_config_dir = + +# Name of configuration file (without .conf suffix) (string value) +#sasl_config_name = + +# SASL realm to use if no realm present in username (string value) +#sasl_default_realm = + +# Seconds to pause before attempting to re-connect. (integer value) +# Minimum value: 1 +#connection_retry_interval = 1 + +# Increase the connection_retry_interval by this many seconds after +# each unsuccessful failover attempt. (integer value) +# Minimum value: 0 +#connection_retry_backoff = 2 + +# Maximum limit for connection_retry_interval + +# connection_retry_backoff (integer value) +# Minimum value: 1 +#connection_retry_interval_max = 30 + +# Time to pause between re-connecting an AMQP 1.0 link that failed due +# to a recoverable error. (integer value) +# Minimum value: 1 +#link_retry_delay = 10 + +# The maximum number of attempts to re-send a reply message which +# failed due to a recoverable error. (integer value) +# Minimum value: -1 +#default_reply_retry = 0 + +# The deadline for an rpc reply message delivery. (integer value) +# Minimum value: 5 +#default_reply_timeout = 30 + +# The deadline for an rpc cast or call message delivery. Only used +# when caller does not provide a timeout expiry. (integer value) +# Minimum value: 5 +#default_send_timeout = 30 + +# The deadline for a sent notification message delivery. Only used +# when caller does not provide a timeout expiry. (integer value) +# Minimum value: 5 +#default_notify_timeout = 30 + +# The duration to schedule a purge of idle sender links. Detach link +# after expiry. (integer value) +# Minimum value: 1 +#default_sender_link_timeout = 600 + +# Indicates the addressing mode used by the driver. +# Permitted values: +# 'legacy' - use legacy non-routable addressing +# 'routable' - use routable addresses +# 'dynamic' - use legacy addresses if the message bus does not +# support routing otherwise use routable addressing (string value) +#addressing_mode = dynamic + +# Enable virtual host support for those message buses that do not +# natively support virtual hosting (such as qpidd). When set to true +# the virtual host name will be added to all message bus addresses, +# effectively creating a private 'subnet' per virtual host. Set to +# False if the message bus supports virtual hosting using the +# 'hostname' field in the AMQP 1.0 Open performative as the name of +# the virtual host. (boolean value) +#pseudo_vhost = true + +# address prefix used when sending to a specific server (string value) +#server_request_prefix = exclusive + +# address prefix used when broadcasting to all servers (string value) +#broadcast_prefix = broadcast + +# address prefix when sending to any server in group (string value) +#group_request_prefix = unicast + +# Address prefix for all generated RPC addresses (string value) +#rpc_address_prefix = openstack.org/om/rpc + +# Address prefix for all generated Notification addresses (string +# value) +#notify_address_prefix = openstack.org/om/notify + +# Appended to the address prefix when sending a fanout message. Used +# by the message bus to identify fanout messages. (string value) +#multicast_address = multicast + +# Appended to the address prefix when sending to a particular +# RPC/Notification server. Used by the message bus to identify +# messages sent to a single destination. (string value) +#unicast_address = unicast + +# Appended to the address prefix when sending to a group of consumers. +# Used by the message bus to identify messages that should be +# delivered in a round-robin fashion across consumers. (string value) +#anycast_address = anycast + +# Exchange name used in notification addresses. +# Exchange name resolution precedence: +# Target.exchange if set +# else default_notification_exchange if set +# else control_exchange if set +# else 'notify' (string value) +#default_notification_exchange = + +# Exchange name used in RPC addresses. +# Exchange name resolution precedence: +# Target.exchange if set +# else default_rpc_exchange if set +# else control_exchange if set +# else 'rpc' (string value) +#default_rpc_exchange = + +# Window size for incoming RPC Reply messages. (integer value) +# Minimum value: 1 +#reply_link_credit = 200 + +# Window size for incoming RPC Request messages (integer value) +# Minimum value: 1 +#rpc_server_credit = 100 + +# Window size for incoming Notification messages (integer value) +# Minimum value: 1 +#notify_server_credit = 100 + +# Send messages of this type pre-settled. +# Pre-settled messages will not receive acknowledgement +# from the peer. Note well: pre-settled messages may be +# silently discarded if the delivery fails. +# Permitted values: +# 'rpc-call' - send RPC Calls pre-settled +# 'rpc-reply'- send RPC Replies pre-settled +# 'rpc-cast' - Send RPC Casts pre-settled +# 'notify' - Send Notifications pre-settled +# (multi valued) +#pre_settled = rpc-cast +#pre_settled = rpc-reply + + +[oslo_messaging_kafka] + +# +# From oslo.messaging +# + +# Max fetch bytes of Kafka consumer (integer value) +#kafka_max_fetch_bytes = 1048576 + +# Default timeout(s) for Kafka consumers (floating point value) +#kafka_consumer_timeout = 1.0 + +# DEPRECATED: Pool Size for Kafka Consumers (integer value) +# This option is deprecated for removal. +# Its value may be silently ignored in the future. +# Reason: Driver no longer uses connection pool. +#pool_size = 10 + +# DEPRECATED: The pool size limit for connections expiration policy +# (integer value) +# This option is deprecated for removal. +# Its value may be silently ignored in the future. +# Reason: Driver no longer uses connection pool. +#conn_pool_min_size = 2 + +# DEPRECATED: The time-to-live in sec of idle connections in the pool +# (integer value) +# This option is deprecated for removal. +# Its value may be silently ignored in the future. +# Reason: Driver no longer uses connection pool. +#conn_pool_ttl = 1200 + +# Group id for Kafka consumer. Consumers in one group will coordinate +# message consumption (string value) +#consumer_group = oslo_messaging_consumer + +# Upper bound on the delay for KafkaProducer batching in seconds +# (floating point value) +#producer_batch_timeout = 0.0 + +# Size of batch for the producer async send (integer value) +#producer_batch_size = 16384 + +# The compression codec for all data generated by the producer. If not +# set, compression will not be used. Note that the allowed values of +# this depend on the kafka version (string value) +# Possible values: +# none - +# gzip - +# snappy - +# lz4 - +# zstd - +#compression_codec = none + +# Enable asynchronous consumer commits (boolean value) +#enable_auto_commit = false + +# The maximum number of records returned in a poll call (integer +# value) +#max_poll_records = 500 + +# Protocol used to communicate with brokers (string value) +# Possible values: +# PLAINTEXT - +# SASL_PLAINTEXT - +# SSL - +# SASL_SSL - +#security_protocol = PLAINTEXT + +# Mechanism when security protocol is SASL (string value) +#sasl_mechanism = PLAIN + +# CA certificate PEM file used to verify the server certificate +# (string value) +#ssl_cafile = + + +[oslo_messaging_notifications] + +# +# From oslo.messaging +# + +# The Drivers(s) to handle sending notifications. Possible values are +# messaging, messagingv2, routing, log, test, noop (multi valued) +# Deprecated group/name - [DEFAULT]/notification_driver +#driver = + +# A URL representing the messaging driver to use for notifications. If +# not set, we fall back to the same configuration used for RPC. +# (string value) +# Deprecated group/name - [DEFAULT]/notification_transport_url +#transport_url = + +# AMQP topic used for OpenStack notifications. (list value) +# Deprecated group/name - [rpc_notifier2]/topics +# Deprecated group/name - [DEFAULT]/notification_topics +#topics = notifications + +# The maximum number of attempts to re-send a notification message +# which failed to be delivered due to a recoverable error. 0 - No +# retry, -1 - indefinite (integer value) +#retry = -1 + + +[oslo_messaging_rabbit] + +# +# From oslo.messaging +# + +# Use durable queues in AMQP. (boolean value) +#amqp_durable_queues = false + +# Auto-delete queues in AMQP. (boolean value) +#amqp_auto_delete = false + +# Connect over SSL. (boolean value) +# Deprecated group/name - [oslo_messaging_rabbit]/rabbit_use_ssl +#ssl = false + +# SSL version to use (valid only if SSL enabled). Valid values are +# TLSv1 and SSLv23. SSLv2, SSLv3, TLSv1_1, and TLSv1_2 may be +# available on some distributions. (string value) +# Deprecated group/name - [oslo_messaging_rabbit]/kombu_ssl_version +#ssl_version = + +# SSL key file (valid only if SSL enabled). (string value) +# Deprecated group/name - [oslo_messaging_rabbit]/kombu_ssl_keyfile +#ssl_key_file = + +# SSL cert file (valid only if SSL enabled). (string value) +# Deprecated group/name - [oslo_messaging_rabbit]/kombu_ssl_certfile +#ssl_cert_file = + +# SSL certification authority file (valid only if SSL enabled). +# (string value) +# Deprecated group/name - [oslo_messaging_rabbit]/kombu_ssl_ca_certs +#ssl_ca_file = + +# EXPERIMENTAL: Run the health check heartbeat thread through a native +# python thread. By default if this option isn't provided the health +# check heartbeat will inherit the execution model from the parent +# process. By example if the parent process have monkey patched the +# stdlib by using eventlet/greenlet then the heartbeat will be run +# through a green thread. (boolean value) +#heartbeat_in_pthread = false + +# How long to wait before reconnecting in response to an AMQP consumer +# cancel notification. (floating point value) +#kombu_reconnect_delay = 1.0 + +# EXPERIMENTAL: Possible values are: gzip, bz2. If not set compression +# will not be used. This option may not be available in future +# versions. (string value) +#kombu_compression = + +# How long to wait a missing client before abandoning to send it its +# replies. This value should not be longer than rpc_response_timeout. +# (integer value) +# Deprecated group/name - [oslo_messaging_rabbit]/kombu_reconnect_timeout +#kombu_missing_consumer_retry_timeout = 60 + +# Determines how the next RabbitMQ node is chosen in case the one we +# are currently connected to becomes unavailable. Takes effect only if +# more than one RabbitMQ node is provided in config. (string value) +# Possible values: +# round-robin - +# shuffle - +#kombu_failover_strategy = round-robin + +# The RabbitMQ login method. (string value) +# Possible values: +# PLAIN - +# AMQPLAIN - +# RABBIT-CR-DEMO - +#rabbit_login_method = AMQPLAIN + +# How frequently to retry connecting with RabbitMQ. (integer value) +#rabbit_retry_interval = 1 + +# How long to backoff for between retries when connecting to RabbitMQ. +# (integer value) +#rabbit_retry_backoff = 2 + +# Maximum interval of RabbitMQ connection retries. Default is 30 +# seconds. (integer value) +#rabbit_interval_max = 30 + +# Try to use HA queues in RabbitMQ (x-ha-policy: all). If you change +# this option, you must wipe the RabbitMQ database. In RabbitMQ 3.0, +# queue mirroring is no longer controlled by the x-ha-policy argument +# when declaring a queue. If you just want to make sure that all +# queues (except those with auto-generated names) are mirrored across +# all nodes, run: "rabbitmqctl set_policy HA '^(?!amq\.).*' '{"ha- +# mode": "all"}' " (boolean value) +#rabbit_ha_queues = false + +# Positive integer representing duration in seconds for queue TTL +# (x-expires). Queues which are unused for the duration of the TTL are +# automatically deleted. The parameter affects only reply and fanout +# queues. (integer value) +# Minimum value: 1 +#rabbit_transient_queues_ttl = 1800 + +# Specifies the number of messages to prefetch. Setting to zero allows +# unlimited messages. (integer value) +#rabbit_qos_prefetch_count = 0 + +# Number of seconds after which the Rabbit broker is considered down +# if heartbeat's keep-alive fails (0 disables heartbeat). (integer +# value) +#heartbeat_timeout_threshold = 60 + +# How often times during the heartbeat_timeout_threshold we check the +# heartbeat. (integer value) +#heartbeat_rate = 2 + +# Enable/Disable the RabbitMQ mandatory flag for direct send. The +# direct send is used as reply, so the MessageUndeliverable exception +# is raised in case the client queue does not exist. (integer value) +#direct_mandatory_flag = True + + +[oslo_middleware] + +# +# From oslo.middleware.http_proxy_to_wsgi +# + +# Whether the application is behind a proxy or not. This determines if +# the middleware should parse the headers or not. (boolean value) +#enable_proxy_headers_parsing = false + + +[oslo_policy] + +# +# From oslo.policy +# + +# This option controls whether or not to enforce scope when evaluating +# policies. If ``True``, the scope of the token used in the request is +# compared to the ``scope_types`` of the policy being enforced. If the +# scopes do not match, an ``InvalidScope`` exception will be raised. +# If ``False``, a message will be logged informing operators that +# policies are being invoked with mismatching scope. (boolean value) +#enforce_scope = false + +# The relative or absolute path of a file that maps roles to +# permissions for a given service. Relative paths must be specified in +# relation to the configuration file setting this option. (string +# value) +#policy_file = policy.json + +# Default rule. Enforced when a requested rule is not found. (string +# value) +#policy_default_rule = default + +# Directories where policy configuration files are stored. They can be +# relative to any directory in the search path defined by the +# config_dir option, or absolute paths. The file defined by +# policy_file must exist for these directories to be searched. +# Missing or empty directories are ignored. (multi valued) +#policy_dirs = policy.d + +# Content Type to send and receive data for REST based policy check +# (string value) +# Possible values: +# application/x-www-form-urlencoded - +# application/json - +#remote_content_type = application/x-www-form-urlencoded + +# server identity verification for REST based policy check (boolean +# value) +#remote_ssl_verify_server_crt = false + +# Absolute path to ca cert file for REST based policy check (string +# value) +#remote_ssl_ca_crt_file = + +# Absolute path to client cert for REST based policy check (string +# value) +#remote_ssl_client_crt_file = + +# Absolute path client key file REST based policy check (string value) +#remote_ssl_client_key_file = + + +[output] + +# +# From cloudkitty.common.config +# + +# Backend for the output manager. (string value) +#backend = cloudkitty.backend.file.FileBackend + +# Storage directory for the file output backend. (string value) +#basepath = /var/lib/cloudkitty/states/ + +# Output pipeline (list value) +#pipeline = osrf + + +[state] + +# +# From cloudkitty.common.config +# + +# Backend for the state manager. (string value) +#backend = cloudkitty.backend.file.FileBackend + +# Storage directory for the file state backend. (string value) +#basepath = /var/lib/cloudkitty/states/ + + +[storage] + +# +# From cloudkitty.common.config +# + +# Name of the storage backend driver. (string value) +#backend = influxdb + +# Storage version to use. (integer value) +# Minimum value: 1 +# Maximum value: 2 +#version = 2 + + +[storage_elasticsearch] + +# +# From cloudkitty.common.config +# + +# Elasticsearch host, along with port and protocol. Defaults to +# http://localhost:9200 (string value) +#host = http://localhost:9200 + +# Elasticsearch index to use. Defaults to "cloudkitty". (string value) +#index_name = cloudkitty + +# Set to true to allow insecure HTTPS connections to Elasticsearch +# (boolean value) +#insecure = false + +# Path of the CA certificate to trust for HTTPS connections. (string +# value) +#cafile = + +# Duration (in seconds) for which the ES scroll contexts should be +# kept alive. (integer value) +# Minimum value: 0 +# Maximum value: 300 +# Advanced Option: intended for advanced users and not used +# by the majority of users, and might have a significant +# effect on stability and/or performance. +#scroll_duration = 30 + + +[storage_gnocchi] + +# +# From cloudkitty.common.config +# + +# endpoint url type (string value) +#interface = internalURL + +# Gnocchi storage archive policy name. (string value) +#archive_policy_name = rating + +# Gnocchi storage archive policy definition. (string value) +#archive_policy_definition = [{"granularity": 3600, "timespan": "90 days"}, {"granularity": 86400, "timespan": "360 days"}, {"granularity": 2592000, "timespan": "1800 days"}] + + +[storage_influxdb] + +# +# From cloudkitty.common.config +# + +# InfluxDB username (string value) +#username = + +# InfluxDB password (string value) +#password = + +# InfluxDB database (string value) +#database = + +# Retention policy to use (string value) +#retention_policy = autogen + +# InfluxDB host (string value) +#host = localhost + +# InfluxDB port (integer value) +#port = 8086 + +# Set to true to use ssl for influxDB connection. Defaults to False +# (boolean value) +#use_ssl = false + +# Set to true to authorize insecure HTTPS connections to influxDB. +# Defaults to False (boolean value) +#insecure = false + +# Path of the CA certificate to trust for HTTPS connections (string +# value) +#cafile = diff --git a/doc/source/admin/configuration/configuration.rst b/doc/source/admin/configuration/configuration.rst index 7adc0361..3e2bcfb8 100644 --- a/doc/source/admin/configuration/configuration.rst +++ b/doc/source/admin/configuration/configuration.rst @@ -2,6 +2,9 @@ Step by step configuration guide ================================ +.. note:: For a sample ``cloudkitty.conf`` file, see + :doc:`samples/cloudkitty-conf` . + Edit ``/etc/cloudkitty/cloudkitty.conf`` to configure cloudkitty. Common options diff --git a/doc/source/admin/configuration/index.rst b/doc/source/admin/configuration/index.rst index c9f9c2fe..b58cdc51 100644 --- a/doc/source/admin/configuration/index.rst +++ b/doc/source/admin/configuration/index.rst @@ -9,4 +9,5 @@ Configuration Guide fetcher collector storage + samples/cloudkitty-conf policy diff --git a/doc/source/admin/configuration/samples/cloudkitty-conf.rst b/doc/source/admin/configuration/samples/cloudkitty-conf.rst new file mode 100644 index 00000000..5cdfdd65 --- /dev/null +++ b/doc/source/admin/configuration/samples/cloudkitty-conf.rst @@ -0,0 +1,5 @@ +========================= +cloudkitty.conf reference +========================= + +.. literalinclude:: ../../../_static/cloudkitty.conf.sample diff --git a/doc/source/admin/configuration/samples/index.rst b/doc/source/admin/configuration/samples/index.rst deleted file mode 100644 index f80f972a..00000000 --- a/doc/source/admin/configuration/samples/index.rst +++ /dev/null @@ -1,11 +0,0 @@ -========================== -Sample configuration files -========================== - -Configuration files can alter how cloudkitty behaves at runtime and by default -are located in ``/etc/cloudkitty/``. Links to sample configuration files can be -found below: - -.. toctree:: - - policy-yaml.rst diff --git a/doc/source/admin/configuration/samples/policy-yaml.rst b/doc/source/admin/configuration/samples/policy-yaml.rst index 4d3bfcb5..c6db952a 100644 --- a/doc/source/admin/configuration/samples/policy-yaml.rst +++ b/doc/source/admin/configuration/samples/policy-yaml.rst @@ -1,3 +1,5 @@ +:orphan: + =========== policy.yaml =========== @@ -5,4 +7,4 @@ policy.yaml Use the ``policy.yaml`` file to define additional access controls that apply to the Rating service: -.. literalinclude:: ../../../_static/policy.yaml.sample +.. literalinclude:: ../../../_static/cloudkitty.policy.yaml.sample diff --git a/doc/source/admin/sample_policy.rst b/doc/source/admin/sample_policy.rst deleted file mode 100644 index 6ee7be62..00000000 --- a/doc/source/admin/sample_policy.rst +++ /dev/null @@ -1,16 +0,0 @@ -======================== -Cloudkitty Sample Policy -======================== - -The following is a sample Cloudkitty policy file that has been auto-generated -from default policy values in code. If you're using the default policies, then -the maintenance of this file is not necessary, and it should not be copied into -a deployment. Doing so will result in duplicate policy definitions. It is here -to help explain which policy operations protect specific Cloudkitty APIs, but -it is not suggested to copy and paste into a deployment unless you're planning -on providing a different policy for an operation that is not the default. - -The sample policy file can also be viewed in -`file form <_static/policy.yaml.sample>`_. - -.. literalinclude:: _static/policy.yaml.sample diff --git a/doc/source/api-reference/v2/dataframes/dataframes_parameters.yml b/doc/source/api-reference/v2/dataframes/dataframes_parameters.yml index 0260c163..d64a3a4d 100644 --- a/doc/source/api-reference/v2/dataframes/dataframes_parameters.yml +++ b/doc/source/api-reference/v2/dataframes/dataframes_parameters.yml @@ -1,3 +1,38 @@ +begin: + in: query + description: | + Begin of the period for which the dataframes are required. + type: iso8601 timestamp + required: false + +end: + in: query + description: | + End of the period for which the dataframes are required. + type: iso8601 timestamp + required: false + +filters: + in: query + description: | + Optional filters. + type: dict + required: false + +limit: + in: query + description: | + For pagination. The maximum number of results to return. + type: int + required: false + +offset: + in: query + description: | + For pagination. The index of the first element that should be returned. + type: int + required: false + dataframes_body: in: body description: | @@ -18,38 +53,3 @@ total_resp: Total of datapoints matching the query parameters. type: int required: true - -limit: - in: query - description: | - For pagination. The maximum number of results to return. - type: int - required: false - -offset: - in: query - description: | - For pagination. The index of the first element that should be returned. - type: int - required: false - -filters: - in: query - description: | - Optional filters. - type: dict - required: false - -begin: - in: query - description: | - Begin of the period for which the dataframes are required. - type: iso8601 timestamp - required: false - -end: - in: query - description: | - End of the period for which the dataframes are required. - type: iso8601 timestamp - required: false diff --git a/doc/source/api-reference/v2/scope/scope_parameters.yml b/doc/source/api-reference/v2/scope/scope_parameters.yml index 90b47cf1..0d5ba0ba 100644 --- a/doc/source/api-reference/v2/scope/scope_parameters.yml +++ b/doc/source/api-reference/v2/scope/scope_parameters.yml @@ -1,3 +1,17 @@ +collector: &collector + in: query + description: | + Filter on collector. + type: string + required: false + +fetcher: &fetcher + in: query + description: | + Filter on fetcher. + type: string + required: false + limit: in: query description: | @@ -19,20 +33,6 @@ scope_id: &scope_id type: string required: false -fetcher: &fetcher - in: query - description: | - Filter on fetcher. - type: string - required: false - -collector: &collector - in: query - description: | - Filter on collector. - type: string - required: false - scope_key: &scope_key in: query description: | @@ -46,23 +46,8 @@ all_scopes: &all_scopes Confirmation whether all scopes must be reset type: bool -state: - in: body - description: | - State of the scope. - type: iso8601 timestamp - required: true - -fetcher_resp: - <<: *fetcher - required: true - description: Fetcher for the given scope - in: body - -scope_id_resp: - <<: *scope_id - required: true - description: Scope +collector_body: + <<: *collector in: body collector_resp: @@ -71,24 +56,39 @@ collector_resp: description: Collector for the given scope in: body -scope_key_resp: - <<: *scope_key - required: true - description: Scope key for the given scope - in: body - -collector_body: - <<: *collector - in: body - fetcher_body: <<: *fetcher in: body +fetcher_resp: + <<: *fetcher + required: true + description: Fetcher for the given scope + in: body + scope_id_body: <<: *scope_id in: body +scope_id_resp: + <<: *scope_id + required: true + description: Scope + in: body + scope_key_body: <<: *scope_key in: body + +scope_key_resp: + <<: *scope_key + required: true + description: Scope key for the given scope + in: body + +state: + in: body + description: | + State of the scope. + type: iso8601 timestamp + required: true diff --git a/doc/source/api-reference/v2/summary/summary_parameters.yml b/doc/source/api-reference/v2/summary/summary_parameters.yml index 138fd58e..f0ebb0a3 100644 --- a/doc/source/api-reference/v2/summary/summary_parameters.yml +++ b/doc/source/api-reference/v2/summary/summary_parameters.yml @@ -1,15 +1,15 @@ -limit: +begin: &begin in: query description: | - For pagination. The maximum number of results to return. - type: int + Begin of the period for which the summary is required. + type: iso8601 timestamp required: false -offset: &offset +end: &end in: query description: | - For pagination. The index of the first element that should be returned. - type: int + End of the period for which the summary is required. + type: iso8601 timestamp required: false filters: @@ -26,34 +26,20 @@ groupby: type: list of strings required: false -begin: &begin +limit: in: query description: | - Begin of the period for which the summary is required. - type: iso8601 timestamp + For pagination. The maximum number of results to return. + type: int required: false -end: &end +offset: &offset in: query description: | - End of the period for which the summary is required. - type: iso8601 timestamp + For pagination. The index of the first element that should be returned. + type: int required: false -qty: &qty - in: body - description: | - Qty for the item. - type: float - required: true - -rate: &rate - in: body - description: | - Rate for the item. - type: float - required: true - begin_resp: <<: *begin required: true @@ -66,12 +52,26 @@ end_resp: description: End of the period for the item. in: body +qty: &qty + in: body + description: | + Qty for the item. + type: float + required: true + qty_resp: <<: *qty required: true description: Qty for the item in the specified period. in: body +rate: &rate + in: body + description: | + Rate for the item. + type: float + required: true + rate_resp: <<: *rate required: true diff --git a/doc/source/conf.py b/doc/source/conf.py index 71694cf5..7800a9fd 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -57,13 +57,19 @@ extensions = ['sphinx.ext.coverage', 'oslo_policy.sphinxpolicygen', ] +# Ignore the following warning: WARNING: while setting up extension +# wsmeext.sphinxext: directive 'autoattribute' is already registered, +# it will be overridden. +suppress_warnings = ['app.add_directive'] + # openstackdocstheme options repository_name = 'openstack/cloudkitty' bug_project = 'cloudkitty' bug_tag = '' +config_generator_config_file = '../../etc/oslo-config-generator/cloudkitty.conf' policy_generator_config_file = '../../etc/oslo-policy-generator/cloudkitty.conf' -sample_policy_basename = '_static/cloudkitty' +sample_policy_basename = sample_config_basename = '_static/cloudkitty' # Add any paths that contain templates here, relative to this directory. # templates_path = [] diff --git a/doc/source/developer/api/tutorial.rst b/doc/source/developer/api/tutorial.rst index 7a371e24..576e0157 100644 --- a/doc/source/developer/api/tutorial.rst +++ b/doc/source/developer/api/tutorial.rst @@ -72,6 +72,7 @@ example endpoint"}**. The ``add_output_schema`` decorator adds voluptuous validation to a method's output. This allows to set defaults. .. autofunction:: cloudkitty.api.v2.utils.add_output_schema + :noindex: Let's update our ``get`` method in order to use this decorator: @@ -108,6 +109,7 @@ parameter. In order to validate it, we'll use the ``add_input_schema`` decorator: .. autofunction:: cloudkitty.api.v2.utils.add_input_schema + :noindex: Arguments validated by the input schema are passed as named arguments to the decorated function. Let's implement the post method. We'll use Werkzeug @@ -157,6 +159,7 @@ query parameters as lists. The ``SingleQueryParam`` helper checks that a parameter is provided only once, and returns it. .. autoclass:: cloudkitty.api.v2.utils.SingleQueryParam + :noindex: .. warning:: ``SingleQueryParam`` uses ``voluptuous.Coerce`` internally for type checking. Thus, ``validation_utils.get_string_type`` cannot @@ -274,6 +277,7 @@ Each endpoint should provide an ``init`` method taking a Flask app as only parameter. This method should call ``do_init``: .. autofunction:: cloudkitty.api.v2.utils.do_init + :noindex: Add the following to ``cloudkitty/api/v2/example/__init__.py``: diff --git a/doc/source/pdf-index.rst b/doc/source/pdf-index.rst index 6c0fa926..a64ac24e 100644 --- a/doc/source/pdf-index.rst +++ b/doc/source/pdf-index.rst @@ -1,3 +1,5 @@ +:orphan: + ====================================== Welcome to CloudKitty's documentation! ====================================== diff --git a/tox.ini b/tox.ini index 1756098d..63797432 100644 --- a/tox.ini +++ b/tox.ini @@ -49,14 +49,14 @@ commands = commands = oslopolicy-sample-generator --config-file=etc/oslo-policy-generator/cloudkitty.conf [testenv:docs] -commands = python setup.py build_sphinx +commands = sphinx-build -W -b html doc/source doc/build/html [testenv:pdf-docs] envdir = {toxworkdir}/docs whitelist_externals = make commands = - sphinx-build -b latex doc/source doc/build/pdf + sphinx-build -W -b latex doc/source doc/build/pdf make -C doc/build/pdf [testenv:venv]