From cab284d6b2edd01c921ba944480702cfb74ffd80 Mon Sep 17 00:00:00 2001 From: Mary Anthony Date: Tue, 12 Jan 2016 17:34:02 -0800 Subject: [PATCH] - Pulling driver specs out of configuruation.md - Fixing index metadata error - Entering all the comments - Updating with the build fixes - Fix Microsoft link broken - Fix collocate, colocate, to unambiguous co-locate Signed-off-by: Mary Anthony --- docs/configuration.md | 552 +++++------------------------ docs/storage-drivers/azure.md | 68 +++- docs/storage-drivers/filesystem.md | 4 +- docs/storage-drivers/gcs.md | 43 +++ docs/storage-drivers/index.md | 7 + docs/storage-drivers/inmemory.md | 9 +- docs/storage-drivers/oss.md | 129 ++++++- docs/storage-drivers/rados.md | 43 +++ docs/storage-drivers/s3.md | 116 +++++- docs/storage-drivers/swift.md | 175 +++++++++ 10 files changed, 651 insertions(+), 495 deletions(-) create mode 100644 docs/storage-drivers/index.md diff --git a/docs/configuration.md b/docs/configuration.md index 7cdfdf40..1c1c99cc 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -112,6 +112,18 @@ information about each option that appears later in this page. region: fr container: containername rootdirectory: /swift/object/name/prefix + oss: + accesskeyid: accesskeyid + accesskeysecret: accesskeysecret + region: OSS region name + endpoint: optional endpoints + internal: optional internal endpoint + bucket: OSS bucket + encrypt: optional data encryption setting + secure: optional ssl setting + chunksize: optional size valye + rootdirectory: optional root directory + inmemory: # This driver takes no parameters delete: enabled: false redirect: @@ -355,7 +367,7 @@ Permitted values are `error`, `warn`, `info` and `debug`. The default is swift: username: username password: password - authurl: https://storage.myprovider.com/v2.0 or https://storage.myprovider.com/v3/auth + authurl: https://storage.myprovider.com/auth/v1.0 or https://storage.myprovider.com/v2.0 or https://storage.myprovider.com/v3/auth tenant: tenantname tenantid: tenantid domain: domain name for Openstack Identity v3 API @@ -364,6 +376,18 @@ Permitted values are `error`, `warn`, `info` and `debug`. The default is region: fr container: containername rootdirectory: /swift/object/name/prefix + oss: + accesskeyid: accesskeyid + accesskeysecret: accesskeysecret + region: OSS region name + endpoint: optional endpoints + internal: optional internal endpoint + bucket: OSS bucket + encrypt: optional data encryption setting + secure: optional ssl setting + chunksize: optional size valye + rootdirectory: optional root directory + inmemory: delete: enabled: false cache: @@ -378,9 +402,63 @@ Permitted values are `error`, `warn`, `info` and `debug`. The default is disable: false The storage option is **required** and defines which storage backend is in use. -You must configure one backend; if you configure more, the registry returns an error. +You must configure one backend; if you configure more, the registry returns an error. You can choose any of these backend storage drivers: -If you are deploying a registry on Windows, be aware that a Windows volume mounted from the host is not recommended. Instead, you can use a S3, or Azure, backing data-store. If you do use a Windows volume, you must ensure that the `PATH` to the mount point is within Windows' `MAX_PATH` limits (typically 255 characters). Failure to do so can result in the following error message: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
filesystemUses the local disk to store registry files. It is ideal for development and may be appropriate for some small-scale production applications. + See the driver's reference documentation. +
azureUses Microsoft's Azure Blob Storage. + See the driver's reference documentation. +
gcsUses Google Cloud Storage. + See the driver's reference documentation. +
radosUses Ceph Object Storage. + See the driver's reference documentation. +
s3Uses Amazon's Simple Storage Service (S3). + See the driver's reference documentation. +
swiftUses Openstack Swift object storage. + See the driver's reference documentation. +
ossUses Aliyun OSS for object storage. + See the driver's reference documentation. +
+ +For purely tests purposes, you can use the [`inmemory` storage +driver](storage-drivers/inmemory.md). If you would like to run a registry from +volatile memory, use the [`filesystem` driver](storage-drivers/filesystem.md) on +a ramdisk. + +If you are deploying a registry on Windows, be aware that a Windows volume +mounted from the host is not recommended. Instead, you can use a S3, or Azure, +backing data-store. If you do use a Windows volume, you must ensure that the +`PATH` to the mount point is within Windows' `MAX_PATH` limits (typically 255 +characters). Failure to do so can result in the following error message: mkdir /XXX protocol error and your registry will not function properly. @@ -446,7 +524,7 @@ The `redirect` subsection provides configuration for managing redirects from content backends. For backends that support it, redirecting is enabled by default. Certain deployment scenarios may prefer to route all data through the Registry, rather than redirecting to the backend. This may be more efficient -when using a backend that is not colocated or when a registry instance is +when using a backend that is not co-located or when a registry instance is doing aggressive caching. Redirects can be disabled by adding a single flag `disable`, set to `true` @@ -455,459 +533,6 @@ under the `redirect` section: redirect: disable: true -### filesystem - -The `filesystem` storage backend uses the local disk to store registry files. It -is ideal for development and may be appropriate for some small-scale production -applications. - -This backend has a single, required `rootdirectory` parameter. The parameter -specifies the absolute path to a directory. The registry stores all its data -here so make sure there is adequate space available. - -### azure - -This storage backend uses Microsoft's Azure Blob Storage. - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ParameterRequiredDescription
- accountname - - yes - - Azure account name. -
- accountkey - - yes - - Azure account key. -
- container - - yes - - Name of the Azure container into which to store data. -
- realm - - no - - Domain name suffix for the Storage Service API endpoint. By default, this - is core.windows.net. -
- -### gcs - -This storage backend uses Google Cloud Storage. - - - - - - - - - - - - - - - - - - - - - - -
ParameterRequiredDescription
- bucket - - yes - - Storage bucket name. -
- keyfile - - no - - A private service account key file in JSON format. Instead of a key file Google Application Default Credentials can be used. -
- rootdirectory - - no - - This is a prefix that will be applied to all Google Cloud Storage keys to allow you to segment data in your bucket if necessary. -
- -### rados - -This storage backend uses [Ceph Object Storage](http://ceph.com/docs/master/rados/). - - - - - - - - - - - - - - - - - - - - - - -
ParameterRequiredDescription
- poolname - - yes - - Ceph pool name. -
- username - - no - - Ceph cluster user to connect as (i.e. admin, not client.admin). -
- chunksize - - no - - Size of the written RADOS objects. Default value is 4MB (4194304). -
- - -### S3 - -This storage backend uses Amazon's Simple Storage Service (S3). - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ParameterRequiredDescription
- accesskey - - yes - - Your AWS Access Key. -
- secretkey - - yes - - Your AWS Secret Key. -
- region - - yes - - The AWS region in which your bucket exists. For the moment, the Go AWS - library in use does not use the newer DNS based bucket routing. -
- bucket - - yes - - The bucket name in which you want to store the registry's data. -
- encrypt - - no - - Specifies whether the registry stores the image in encrypted format or - not. A boolean value. The default is false. -
- secure - - no - - Indicates whether to use HTTPS instead of HTTP. A boolean value. The - default is true. -
- v4auth - - no - - Indicates whether the registry uses Version 4 of AWS's authentication. - Generally, you should set this to true. By default, this is - false. -
- chunksize - - no - - The S3 API requires multipart upload chunks to be at least 5MB. This value - should be a number that is larger than 5*1024*1024. -
- rootdirectory - - no - - This is a prefix that will be applied to all S3 keys to allow you to segment data in your bucket if necessary. -
- -### Openstack Swift - -This storage backend uses Openstack Swift object storage. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ParameterRequiredDescription
- authurl - - yes - - URL for obtaining an auth token. https://storage.myprovider.com/v2.0 or https://storage.myprovider.com/v3/auth -
- username - - yes - - Your Openstack user name. -
- password - - yes - - Your Openstack password. -
- region - - no - - The Openstack region in which your container exists. -
- container - - yes - - The name of your Swift container where you wish to store the registry's data. The driver creates the named container during its initialization. -
- tenant - - no - - Your Openstack tenant name. You can either use tenant or tenantid. -
- tenantid - - no - - Your Openstack tenant id. You can either use tenant or tenantid. -
- domain - - no - - Your Openstack domain name for Identity v3 API. You can either use domain or domainid. -
- domainid - - no - - Your Openstack domain id for Identity v3 API. You can either use domain or domainid. -
- trustid - - no - - Your Openstack trust id for Identity v3 API. -
- insecureskipverify - - no - - true to skip TLS verification, false by default. -
- chunksize - - no - - Size of the data segments for the Swift Dynamic Large Objects. This value should be a number (defaults to 5M). -
- prefix - - no - - This is a prefix that will be applied to all Swift keys to allow you to segment data in your container if necessary. Defaults to the empty string which is the container's root. -
- secretkey - - no - - The secret key used to generate temporary URLs. -
- accesskey - - no - - The access key to generate temporary URLs. It is used by HP Cloud Object Storage in addition to the `secretkey` parameter. -
- ## auth @@ -1035,11 +660,12 @@ For more information about Token based authentication configuration, see the [sp ### htpasswd The _htpasswd_ authentication backed allows one to configure basic auth using an -[Apache HTPasswd File](https://httpd.apache.org/docs/2.4/programs/htpasswd.html). -Only [`bcrypt`](http://en.wikipedia.org/wiki/Bcrypt) format passwords are -supported. Entries with other hash types will be ignored. The htpasswd file is -loaded once, at startup. If the file is invalid, the registry will display an -error and will not start. +[Apache htpasswd +file](https://httpd.apache.org/docs/2.4/programs/htpasswd.html). Only +[`bcrypt`](http://en.wikipedia.org/wiki/Bcrypt) format passwords are supported. +Entries with other hash types will be ignored. The htpasswd file is loaded once, +at startup. If the file is invalid, the registry will display an error and will +not start. > __WARNING:__ This authentication scheme should only be used with TLS > configured, since basic authentication sends passwords as part of the http @@ -1078,7 +704,7 @@ error and will not start. ## middleware The `middleware` option is **optional**. Use this option to inject middleware at -named hook points. All middlewares must implement the same interface as the +named hook points. All middleware must implement the same interface as the object they're wrapping. This means a registry middleware must implement the `distribution.Namespace` interface, repository middleware must implement `distribution.Repository`, and storage middleware must implement diff --git a/docs/storage-drivers/azure.md b/docs/storage-drivers/azure.md index f994f38a..2783c427 100644 --- a/docs/storage-drivers/azure.md +++ b/docs/storage-drivers/azure.md @@ -9,16 +9,68 @@ keywords = ["registry, service, driver, images, storage, azure"] # Microsoft Azure storage driver -An implementation of the `storagedriver.StorageDriver` interface which uses [Microsoft Azure Blob Storage][azure-blob-storage] for object storage. +An implementation of the `storagedriver.StorageDriver` interface which uses [Microsoft Azure Blob Storage](http://azure.microsoft.com/en-us/services/storage/) for object storage. ## Parameters -The following parameters must be used to authenticate and configure the storage driver (case-sensitive): + + + + + + + + + + + + + + + + + + + + + + + + + + -* `accountname`: Name of the Azure Storage Account. -* `accountkey`: Primary or Secondary Key for the Storage Account. -* `container`: Name of the root storage container in which all registry data will be stored. Must comply the storage container name [requirements][create-container-api]. -* `realm`: (optional) Domain name suffix for the Storage Service API endpoint. Defaults to `core.windows.net`. For example realm for "Azure in China" would be `core.chinacloudapi.cn` and realm for "Azure Government" would be `core.usgovcloudapi.net`. +
ParameterRequiredDescription
+ accountname + + yes + + Name of the Azure Storage Account. +
+ accountkey + + yes + + Primary or Secondary Key for the Storage Account. +
+ container + + yes + + Name of the Azure root storage container in which all registry data will be stored. Must comply the storage container name [requirements][create-container-api]. +
+ realm + + no + + Domain name suffix for the Storage Service API endpoint. For example realm for "Azure in China" would be `core.chinacloudapi.cn` and realm for "Azure Government" would be `core.usgovcloudapi.net`. By default, this + is core.windows.net. +
-[azure-blob-storage]: http://azure.microsoft.com/en-us/services/storage/ -[create-container-api]: https://msdn.microsoft.com/en-us/library/azure/dd179468.aspx + +## Related Information + +* To get information about +[azure-blob-storage](http://azure.microsoft.com/en-us/services/storage/) visit +the Microsoft website. +* You can use Microsoft's [Blob Service REST API](https://msdn.microsoft.com/en-us/library/azure/dd135733.aspx) to [create a container] (https://msdn.microsoft.com/en-us/library/azure/dd179468.aspx). diff --git a/docs/storage-drivers/filesystem.md b/docs/storage-drivers/filesystem.md index 2dbad8cd..476edcf5 100644 --- a/docs/storage-drivers/filesystem.md +++ b/docs/storage-drivers/filesystem.md @@ -13,4 +13,6 @@ An implementation of the `storagedriver.StorageDriver` interface which uses the ## Parameters -`rootdirectory`: (optional) The root directory tree in which all registry files will be stored. Defaults to `/var/lib/registry`. +`rootdirectory`: (optional) The absolute path to a root directory tree in which +to store all registry files. The registry stores all its data here so make sure +there is adequate space available. Defaults to `/var/lib/registry`. diff --git a/docs/storage-drivers/gcs.md b/docs/storage-drivers/gcs.md index bb6f2b01..33cc94b3 100644 --- a/docs/storage-drivers/gcs.md +++ b/docs/storage-drivers/gcs.md @@ -13,6 +13,49 @@ An implementation of the `storagedriver.StorageDriver` interface which uses Goog ## Parameters + + + + + + + + + + + + + + + + + + + + + + +
ParameterRequiredDescription
+ bucket + + yes + + Storage bucket name. +
+ keyfile + + no + + A private service account key file in JSON format. Instead of a key file Google Application Default Credentials can be used. +
+ rootdirectory + + no + + This is a prefix that will be applied to all Google Cloud Storage keys to allow you to segment data in your bucket if necessary. +
+ + `bucket`: The name of your Google Cloud Storage bucket where you wish to store objects (needs to already be created prior to driver initialization). `keyfile`: (optional) A private key file in JSON format, used for [Service Account Authentication](https://cloud.google.com/storage/docs/authentication#service_accounts). diff --git a/docs/storage-drivers/index.md b/docs/storage-drivers/index.md new file mode 100644 index 00000000..2de729ad --- /dev/null +++ b/docs/storage-drivers/index.md @@ -0,0 +1,7 @@ + diff --git a/docs/storage-drivers/inmemory.md b/docs/storage-drivers/inmemory.md index f43e1510..3109891e 100644 --- a/docs/storage-drivers/inmemory.md +++ b/docs/storage-drivers/inmemory.md @@ -7,11 +7,14 @@ keywords = ["registry, service, driver, images, storage, in-memory"] -# In-memory storage driver +# In-memory storage driver (Testing Only) -An implementation of the `storagedriver.StorageDriver` interface which uses local memory for object storage. +For purely tests purposes, you can use the `inmemory` storage driver. This +driver is an implementation of the `storagedriver.StorageDriver` interface which +uses local memory for object storage. If you would like to run a registry from +volatile memory, use the [`filesystem` driver](filesystem.md) on a ramdisk. -**IMPORTANT**: This storage driver *does not* persist data across runs, and primarily exists for testing. +**IMPORTANT**: This storage driver *does not* persist data across runs. This is why it is only suitable for testing. *Never* use this driver in production. ## Parameters diff --git a/docs/storage-drivers/oss.md b/docs/storage-drivers/oss.md index f6f2de97..2087c98d 100755 --- a/docs/storage-drivers/oss.md +++ b/docs/storage-drivers/oss.md @@ -12,22 +12,113 @@ An implementation of the `storagedriver.StorageDriver` interface which uses [Ali ## Parameters -* `accesskeyid`: Your access key ID. - -* `accesskeysecret`: Your access key secret. - -* `region`: The name of the OSS region in which you would like to store objects (for example `oss-cn-beijing`). For a list of regions, you can look at - -* `endpoint`: (optional) By default, the endpoint shoulb be `..aliyuncs.com` or `.-internal.aliyuncs.com` (when internal=true). You can change the default endpoint via changing this value. - -* `internal`: (optional) Using internal endpoint or the public endpoint for OSS access. The default is false. For a list of regions, you can look at - -* `bucket`: The name of your OSS bucket where you wish to store objects (needs to already be created prior to driver initialization). - -* `encrypt`: (optional) Whether you would like your data encrypted on the server side (defaults to false if not specified). - -* `secure`: (optional) Whether you would like to transfer data to the bucket over ssl or not. Defaults to true if not specified. - -* `chunksize`: (optional) The default part size for multipart uploads (performed by WriteStream) to OSS. The default is 10 MB. Keep in mind that the minimum part size for OSS is 5MB. You might experience better performance for larger chunk sizes depending on the speed of your connection to OSS. - -* `rootdirectory`: (optional) The root directory tree in which all registry files will be stored. Defaults to the empty string (bucket root). + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterRequiredDescription
+ accesskeyid + +yes + +Your access key ID. +
+ accesskeysecret + +yes + +Your access key secret. +
+ region + +yes + The name of the OSS region in which you would like to store objects (for example `oss-cn-beijing`). For a list of regions, you can look at +
+ endpoint + +no + +An endpoint which defaults to `..aliyuncs.com` or `.-internal.aliyuncs.com` (when `internal=true`). You can change the default endpoint by changing this value. +
+ internal + +no + An internal endpoint or the public endpoint for OSS access. The default is false. For a list of regions, you can look at +
+ bucket + +yes + The name of your OSS bucket where you wish to store objects (needs to already be created prior to driver initialization). +
+ encrypt + +no + Specifies whether you would like your data encrypted on the server side. Defaults to false if not specified. +
+ secure + +no + Specifies whether to transfer data to the bucket over ssl or not. If you omit this value, `true` is used. +
+ chunksize + +no + The default part size for multipart uploads (performed by WriteStream) to OSS. The default is 10 MB. Keep in mind that the minimum part size for OSS is 5MB. You might experience better performance for larger chunk sizes depending on the speed of your connection to OSS. +
+ rootdirectory + +no + The root directory tree in which to store all registry files. Defaults to an empty string (bucket root). +
diff --git a/docs/storage-drivers/rados.md b/docs/storage-drivers/rados.md index 4b630e19..12643b2a 100644 --- a/docs/storage-drivers/rados.md +++ b/docs/storage-drivers/rados.md @@ -14,6 +14,49 @@ An implementation of the `storagedriver.StorageDriver` interface which uses ## Parameters + + + + + + + + + + + + + + + + + + + + + + +
ParameterRequiredDescription
+ poolname + + yes + + Ceph pool name. +
+ username + + no + + Ceph cluster user to connect as (i.e. admin, not client.admin). +
+ chunksize + + no + + Size of the written RADOS objects. Default value is 4MB (4194304). +
+ + The following parameters must be used to configure the storage driver (case-sensitive): diff --git a/docs/storage-drivers/s3.md b/docs/storage-drivers/s3.md index 0f4326fa..5b172f9e 100644 --- a/docs/storage-drivers/s3.md +++ b/docs/storage-drivers/s3.md @@ -13,6 +13,120 @@ An implementation of the `storagedriver.StorageDriver` interface which uses Amaz ## Parameters + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterRequiredDescription
+ accesskey + + yes + + Your AWS Access Key. +
+ secretkey + + yes + + Your AWS Secret Key. +
+ region + + yes + + The AWS region in which your bucket exists. For the moment, the Go AWS + library in use does not use the newer DNS based bucket routing. +
+ bucket + + yes + + The bucket name in which you want to store the registry's data. +
+ encrypt + + no + + Specifies whether the registry stores the image in encrypted format or + not. A boolean value. The default is false. +
+ secure + + no + + Indicates whether to use HTTPS instead of HTTP. A boolean value. The + default is true. +
+ v4auth + + no + + Indicates whether the registry uses Version 4 of AWS's authentication. + Generally, you should set this to true. By default, this is + false. +
+ chunksize + + no + + The S3 API requires multipart upload chunks to be at least 5MB. This value + should be a number that is larger than 5*1024*1024. +
+ rootdirectory + + no + + This is a prefix that will be applied to all S3 keys to allow you to segment data in your bucket if necessary. +
+ + `accesskey`: Your aws access key. `secretkey`: Your aws secret key. @@ -80,4 +194,4 @@ middleware: ## CloudFront Key-Pair -A CloudFront key-pair is required for all AWS accounts needing access to your CloudFront distribution. For information, please see [Creating CloudFront Key Pairs](http://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/private-content-trusted-signers.html#private-content-creating-cloudfront-key-pairs). \ No newline at end of file +A CloudFront key-pair is required for all AWS accounts needing access to your CloudFront distribution. For information, please see [Creating CloudFront Key Pairs](http://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/private-content-trusted-signers.html#private-content-creating-cloudfront-key-pairs). diff --git a/docs/storage-drivers/swift.md b/docs/storage-drivers/swift.md index ca17e9ff..cab0bbd2 100644 --- a/docs/storage-drivers/swift.md +++ b/docs/storage-drivers/swift.md @@ -13,6 +13,181 @@ An implementation of the `storagedriver.StorageDriver` interface that uses [Open ## Parameters + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterRequiredDescription
+ authurl + + yes + + URL for obtaining an auth token. https://storage.myprovider.com/v2.0 or https://storage.myprovider.com/v3/auth +
+ username + + yes + + Your Openstack user name. +
+ password + + yes + + Your Openstack password. +
+ region + + no + + The Openstack region in which your container exists. +
+ container + + yes + + The name of your Swift container where you wish to store the registry's data. The driver creates the named container during its initialization. +
+ tenant + + no + + Your Openstack tenant name. You can either use tenant or tenantid. +
+ tenantid + + no + + Your Openstack tenant id. You can either use tenant or tenantid. +
+ domain + + no + + Your Openstack domain name for Identity v3 API. You can either use domain or domainid. +
+ domainid + + no + + Your Openstack domain id for Identity v3 API. You can either use domain or domainid. +
+ trustid + + no + + Your Openstack trust id for Identity v3 API. +
+ insecureskipverify + + no + + true to skip TLS verification, false by default. +
+ chunksize + + no + + Size of the data segments for the Swift Dynamic Large Objects. This value should be a number (defaults to 5M). +
+ prefix + + no + + This is a prefix that will be applied to all Swift keys to allow you to segment data in your container if necessary. Defaults to the empty string which is the container's root. +
+ secretkey + + no + + The secret key used to generate temporary URLs. +
+ accesskey + + no + + The access key to generate temporary URLs. It is used by HP Cloud Object Storage in addition to the `secretkey` parameter. +
+ +