Merge "Improve documentation in the swift.yml file"

2015-01-22 11:39:25 +00:00 · 2015-01-22 11:39:25 +00:00 · 03b6a6d632
commit 03b6a6d632
parent 1b0e507472 109c875509
1 changed files with 225 additions and 57 deletions
--- a/etc/rpc_deploy/conf.d/swift.yml
+++ b/etc/rpc_deploy/conf.d/swift.yml
@ -1,40 +1,233 @@
 ---
-## Swift group variables are required only when using swift.
-## Below is a sample configuration.
-##
-## part_power value is required at the swift_level and cannot be changed once the ring has been built without removing the rings manually and rerunning the ring_builder.
-##
-## The weight value is not required, and will default to 100 if not specified. This value will apply to all drives setup, but can be overriden on a drive or node basis by setting this value in the node or drive config.
-##
-## The min_part_hours and repl_number values are not required, and will default to "1" and "3" respectively. Setting these at the swift level will apply this value as a default for all rings (including account/container). These can be overriden on a per ring basis by adjusting the value for account/container or specific storage_policy.
-##
-## If you are using a storage_network specify the interface that the storage_network is setup on. If this value isn't specified the swift services will listen on the default management ip. NB If the storage_network isn't set but storage_ip's per host are set (or the storage_ip is not on the storage_network interface) the proxy server will not be able to connect to the storage services as this directly changes the IP address the storage hosts are listening on.
-##
-## If you are using a dedicated replication network specify the interface that the storage_network is setup on. If this value isn't specified no dedicated replication_network will be set. As with the storage_network this impacts the IP that the replication service listens on, if the repl_ip isn't set on that interface replication will not work properly.
-##
-## Set the default drives per host. This is useful when all hosts have the exact same drives. This can be overridden on a "per host" basis.
-##
-## Set the default mount_point - which is the location where your swift drives are mounted. For example with a mount point of /mnt and a drive of sdc there should be a drive mounted at /mnt/sdc on the swift_host. This can be overriden on a per host basis if required.
-##
-## For account and container rings, min_part_hours and repl_number are the only values that can be set. Setting them here will override the defaults for the specific ring.
-##
-## Specify your storage_policies, there must be atleast one storage policy, and atleast one storage policy with index of 0 for legacy containers created before storage policies were instituted. At least one storage policy must have "default: True" set. The options that can be set for storage_policies are name (str), index (int), default (bool), deprecated (bool), repl_number (int) and min_part_hours (int) - with the last 2 overriding the default if specified.
-##
+# Copyright 2015, Rackspace US, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# Overview
+# ========
+#
+# This file contains the configuration for the Object Storage (swift)
+# service. Only enable these options for environments that contain the
+# Object Storage service. For more information on Object Storage options,
+# see the documentation at
+#
+# http://docs.openstack.org/developer/swift/index.html
+#
+# The hierarchical structure of this file supports overrides for most
+# options. However, for typical deployments, defining options closest
+# to the top level provides a functional configuration.
+#
+# Configuration reference
+# =======================
+#
+# Level: swift (required)
+# Contains global options.
+#
+#   Option: storage_network (optional, string)
+#   Network to use for object storage operations. Defaults to the management
+#   network if omitted.
+#   If using a storage network, specify the network bridge containing it,
+#   typically 'br-storage'.
+#
+#   Option: repl_network (optional, string)
+#   Network to use for object replication operations. Defaults to the
+#   'storage_network' value if omitted.
+#   If using a replication network, specify the network bridge containing it,
+#   typically 'br-repl'.
+#
+#   Option: part_power (required, integer)
+#   Partition power. Immutable without rebuilding the rings.
+#   Applies to all rings unless overridden at the 'account' or 'container'
+#   levels or within a policy under the 'storage_policies' level.
+#
+#   Option: repl_number (optional, integer)
+#   Number of replicas for each partition. Defaults to 3.
+#   Applies to all rings unless overridden at the 'account' or 'container'
+#   levels or within a policy under the 'storage_policies' level.
+#
+#   Option: min_part_hours (optional, integer)
+#   Minimum time in hours between multiple moves of the same partition.
+#   Defaults to 1.
+#   Applies to all rings unless overridden at the 'account' or 'container'
+#   levels or within a policy under the 'storage_policies' level.
+#
+#   Option: region (optional, integer)
+#   Region of a disk. Defaults to 1.
+#   Applies to all disks in all hosts unless overridden deeper in the
+#   structure.
+#
+#   Option: zone (optional, integer)
+#   Zone of a disk. Defaults to 0.
+#   Applies to all disks in all hosts unless overridden deeper in the
+#   structure.
+#
+#   Option: weight (optional, integer)
+#   Weight of a disk. Defaults to 100.
+#   Applies to all disks in all hosts unless overridden deeper in the
+#   structure.
+#
+#   Option: mount_point (required, string)
+#   Top-level directory for mount points of disks. Defaults to /mnt.
+#   Applies to all hosts unless overridden deeper in the structure.
+#
+#   Level: drives (required)
+#   Contains the mount points of disks.
+#   Applies to all hosts unless overridden deeper in the structure.
+#
+#     Option: name (required, string)
+#     Mount point of a disk. Use one entry for each disk.
+#     Applies to all hosts unless overridden deeper in the structure.
+#
+#     The following example shows disks mounted at /mnt/sda and /mnt/sdb
+#     on all storage hosts:
+#       mount_point: /mnt
+#       drives:
+#         - name: sda
+#         - name: sdb
+#
+#   Level: account (optional)
+#   Contains 'min_part_hours' and 'repl_number' options specific to the
+#   account ring.
+#
+#   Level: container (optional)
+#   Contains 'min_part_hours' and 'repl_number' options specific to the
+#   container ring.
+#
+#   Level: storage_policies (required)
+#   Contains storage policies. Minimum one policy. One policy must include
+#   the 'index: 0' and 'default: True' options.
+#
+#     Level: policy (required)
+#     Contains a storage policy.
+#
+#       Option: name (required, string)
+#       Policy name.
+#
+#       Option: index (required, integer)
+#       Policy index. One policy must include this option with a '0'
+#       value.
+#
+#       Option: default (optional, boolean)
+#       Defines the default policy. One policy must include this option
+#       with a 'True' value.
+#
+#       Option: deprecated (optional, boolean)
+#       Defines a deprecated policy.
+#
+#       Note: The following levels and options override any values higher
+#       in the structure and generally apply to advanced deployments.
+#
+#       Option: repl_number (optional, integer)
+#       Number of replicas of each partition in this policy.
+#
+#       Option: min_part_hours (optional, integer)
+#       Minimum time between multiple moves of the same partition in this
+#       policy.
+#
+# Level: swift_proxy-hosts (required)
+# Contains definitions for proxy hosts.
+#
+#   Level: <value> (optional, string)
+#   Name of a proxy host. Typical deployments require at least three
+#   proxy hosts.
+#
+#     Option: ip (required, string)
+#     IP address of the host.
+#
+# Level: swift_hosts (required)
+# Contains definitions for storage hosts.
+#
+#   Level: <value> (required, string)
+#   Name of a storage host. Typical deployments require at least three
+#   storage hosts.
+#
+#     Option: ip (required, string)
+#     IP address of the host.
+#
+#     Note: The following levels and options override any values higher
+#     in the structure and generally apply to advanced deployments.
+#
+#     Level: container_vars (optional)
+#     Contains options specific to this host.
+#
+#       Level: swift_vars (optional)
+#       Contains swift options specific to this host.
+#
+#         Option: region (optional, integer)
+#         Region of all disks in this host.
+#
+#         Option: zone (optional, integer)
+#         Zone of all disks in this host.
+#
+#         Option: weight (optional, integer)
+#         Weight of all disks in this host.
+#
+#         Level: groups (optional)
+#         Contains groups specific to this host.
+#         The following example shows a storage host with the account ring,
+#         container ring, and 'silver' storage policy:
+#           groups:
+#             - account
+#             - container
+#             - silver
+#
+#         Level: drives (optional)
+#         Contains the mount points of disks specific to this host.
+#
+#         Level or option: name (optional, string)
+#         Mount point of a disk specific to this host. Use one entry for
+#         each disk. Functions as a level for disks that contain additional
+#         options.
+#
+#           Option: region (optional, integer)
+#           Region of a disk in this host.
+#
+#           Option: zone (optional, integer)
+#           Zone of a disk in this host.
+#
+#           Option: weight (optional, integer)
+#           Weight of a disk in this host.
+#
+#           Level: groups (optional)
+#           Contains groups for a disk in this host.
+#           The following example shows a disk with the account ring,
+#           container ring, and 'silver' storage policy:
+#             groups:
+#               - account
+#               - container
+#               - silver
+
+# Default (example) configuration
+# ===============================
+
+# Global options

 # global_overrides:
 #   swift:
-#     part_power: 8
-#     weight: 100
-#     min_part_hours: 1
-#     repl_number: 3
 #     storage_network: 'br-storage'
 #     replication_network: 'br-repl'
+#     part_power: 8
+#     repl_number: 3
+#     min_part_hours: 1
+#     region: 1
+#     zone: 0
+#     weight: 100
+#     mount_point: /mnt
 #     drives:
 #       - name: sdc
 #       - name: sdd
 #       - name: sde
 #       - name: sdf
-#     mount_point: /mnt
 #     account:
 #     container:
 #     storage_policies:
@ -48,8 +241,7 @@
 #           repl_number: 3
 #           deprecated: True

-## Specify the swift-proxy_hosts - these will typically be your infra nodes and are where your swift_proxy containers will be created.
-## All that is required is the IP address of the host that ansible will connect to.
+# Proxy hosts

 # swift-proxy_hosts:
 #   infra-node1:
@ -59,41 +251,18 @@
 #   infra-node3:
 #     ip: 192.0.2.3

-## Specify the swift_hosts which will be the swift storage nodes.
-##
-## The ip is the address of the host that ansible will connect to.
-##
-## all swift settings are set under swift_vars.
-##
-## The storage_ip and repl_ip represent the IP that will go in the ring for storage and replication.
-## These will be pulled from the server's interface (specified by storage_network & replication_network), but can be overriden by specifying them at the node or drive level.
-## If only the storage_ip is specified then the repl_ip will default to the storage_ip
-## If only the repl_ip is specified then the storage_ip will default to the host ip above.
-## If neither are specified both will default to the host ip above.
-##
-## zone and region can be specified for swift when building the ring.
-##
-## groups can be set to list which rings a host's drive should belong to. This can be set on a per drive basis which will override the host setting.
-##
-## swift-node5 is an example of overriding the values. Where the groups are set, and overridden on drive sdb. The weight is overriden for the host, and specifically adjusted on drive sdb, and the storage/repl_ip's are different for sdb.
-##
+# Storage hosts
+#
+# The first three hosts contain options for typical deployments. Hosts
+# four and five show options for more advanced deployments.

 # swift_hosts:
 #   swift-node1:
 #     ip: 192.0.2.4
-#     container_vars:
-#       swift_vars:
-#         zone: 0
 #   swift-node2:
 #     ip: 192.0.2.5
-#     container_vars:
-#       swift_vars:
-#         zone: 1
 #   swift-node3:
 #     ip: 192.0.2.6
-#     container_vars:
-#       swift_vars:
-#         zone: 2
 #   swift-node4:
 #     ip: 192.0.2.7
 #     container_vars:
@ -105,8 +274,8 @@
 #       swift_vars:
 #         storage_ip: 198.51.100.8
 #         repl_ip: 203.0.113.8
-#         zone: 4
 #         region: 3
+#         zone: 4
 #         weight: 200
 #         groups:
 #           - account
@ -123,4 +292,3 @@
 #           - name: sdd
 #           - name: sde
 #           - name: sdf
-