You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@buildstream.apache.org by tv...@apache.org on 2021/01/28 08:03:53 UTC
[buildstream] 02/02: doc: Ammending documentation for new "servers"
list of cache configuration
This is an automated email from the ASF dual-hosted git repository.
tvb pushed a commit to branch tristan/change-remote-config
in repository https://gitbox.apache.org/repos/asf/buildstream.git
commit 0d8b3b119c17ae992ebc423f1485fec8a06407a5
Author: Tristan van Berkom <tr...@codethink.co.uk>
AuthorDate: Thu Jan 28 16:57:49 2021 +0900
doc: Ammending documentation for new "servers" list of cache configuration
And documenting the new "override-project-caches" attribute for cache
configurations.
---
doc/source/format_project.rst | 7 ++-
doc/source/using_config.rst | 134 ++++++++++++++++++++++++------------------
2 files changed, 82 insertions(+), 59 deletions(-)
diff --git a/doc/source/format_project.rst b/doc/source/format_project.rst
index 0a7d6ef..66bc126 100644
--- a/doc/source/format_project.rst
+++ b/doc/source/format_project.rst
@@ -200,7 +200,8 @@ When maintaining a BuildStream project, it can be convenient to downstream users
of your project to provide access to a :ref:`cache server <cache_servers>` you maintain.
The project can provide *recommended* artifact cache servers through project configuration
-using the same semantics as one normally uses in :ref:`user configuration <config_cache_servers>`:
+using the same semantics as one normally uses in the ``servers`` list of the
+:ref:`cache server user configuration <config_cache_servers>`:
.. code:: yaml
@@ -231,8 +232,8 @@ using the same semantics as one normally uses in :ref:`user configuration <confi
Source cache server
~~~~~~~~~~~~~~~~~~~
In the same way as artifact cache servers, the project can provide *recommended* source cache
-servers through project configuration using the same semantics as one normally uses in
-:ref:`user configuration <config_cache_servers>`:
+servers through project configuration using the same semantics as one normally uses in the
+``servers`` list of the :ref:`cache server user configuration <config_cache_servers>`:
.. code:: yaml
diff --git a/doc/source/using_config.rst b/doc/source/using_config.rst
index c4b4c18..b438c47 100644
--- a/doc/source/using_config.rst
+++ b/doc/source/using_config.rst
@@ -118,59 +118,73 @@ Cache server configuration is declared in the following way:
.. code:: yaml
- url: https://cache-server.com/cache:11001
- instance-name: main
- type: both
- push: true
- auth:
- server-cert: server.crt
- client-cert: client.crt
- client-key: client.key
+ override-project-caches: false
+ servers:
+ - url: https://cache-server.com/cache:11001
+ instance-name: main
+ type: both
+ push: true
+ auth:
+ server-cert: server.crt
+ client-cert: client.crt
+ client-key: client.key
**Attributes:**
-* ``url``
+* ``override-project-caches``
- Indicates the ``http`` or ``https`` url and optionally the port number of
- where the cache server is located.
+ Whether this user configuration overrides the project recommendations for
+ :ref:`artifact caches <project_artifact_cache>` or :ref:`source caches <project_source_cache>`.
-* ``instance-name``
+ If this is false (which is the default), then project recommended cache
+ servers will be observed after user specified caches.
- Instance names separate different shards on the same endpoint (``url``).
+* ``servers``
- The instance name is optional, and not all cache server implementations support
- instance names. The instance name should be given to you by the
- service provider of each service.
+ This is the list of cache servers in the configuration block, every entry
+ in the block represents a server which will be accessed in the specified order.
-* ``type``
+ * ``url``
- The type of service you intend to use this cache server for. If unspecified,
- the default value for this field is ``both``.
+ Indicates the ``http`` or ``https`` url and optionally the port number of
+ where the cache server is located.
- * ``storage``
+ * ``instance-name``
- Use this cache service for storage.
+ Instance names separate different shards on the same endpoint (``url``).
- * ``index``
+ The instance name is optional, and not all cache server implementations support
+ instance names. The instance name should be given to you by the
+ service provider of each service.
- Use this cache service for index content expected to be present in one
- or more *storage* services.
+ * ``type``
- * ``both``
+ The type of service you intend to use this cache server for. If unspecified,
+ the default value for this field is ``both``.
- Use this cache service for both indexing and storing data.
+ * ``storage``
+ Use this cache service for storage.
-* ``push``
+ * ``index``
- Set this to ``true`` if you intend to upload data to this cache server.
+ Use this cache service for index content expected to be present in one
+ or more *storage* services.
- Normally this requires additional credentials in the ``auth`` field.
+ * ``both``
-* ``auth``
+ Use this cache service for both indexing and storing data.
- The :ref:`authentication attributes <config_remote_auth>` to connect to
- this server.
+ * ``push``
+
+ Set this to ``true`` if you intend to upload data to this cache server.
+
+ Normally this requires additional credentials in the ``auth`` field.
+
+ * ``auth``
+
+ The :ref:`authentication attributes <config_remote_auth>` to connect to
+ this server.
.. _config_cache_server_list:
@@ -226,12 +240,14 @@ toplevel of the user configuration.
# Configure a global artifact server for pushing and pulling artifacts
#
artifacts:
- - url: https://artifacts.com/artifacts:11001
- push: true
- auth:
- server-cert: server.crt
- client-cert: client.crt
- client-key: client.key
+ override-project-caches: false
+ servers:
+ - url: https://artifacts.com/artifacts:11001
+ push: true
+ auth:
+ server-cert: server.crt
+ client-cert: client.crt
+ client-key: client.key
Project overrides
@@ -252,12 +268,14 @@ artifact cache servers declared in the global caches.
projects:
foo:
artifacts:
- - url: https://artifacts.com/artifacts:11001
- push: true
- auth:
- server-cert: server.crt
- client-cert: client.crt
- client-key: client.key
+ override-project-caches: false
+ servers:
+ - url: https://artifacts.com/artifacts:11001
+ push: true
+ auth:
+ server-cert: server.crt
+ client-cert: client.crt
+ client-key: client.key
Project recommendations
@@ -297,12 +315,14 @@ toplevel of the user configuration.
# Configure a global source cache server for pushing and pulling sources
#
source-caches:
- - url: https://sources.com/sources:11001
- push: true
- auth:
- server-cert: server.crt
- client-cert: client.crt
- client-key: client.key
+ override-project-caches: false
+ servers:
+ - url: https://sources.com/sources:11001
+ push: true
+ auth:
+ server-cert: server.crt
+ client-cert: client.crt
+ client-key: client.key
Project overrides
@@ -323,12 +343,14 @@ source cache servers declared in the global caches.
projects:
foo:
source-caches:
- - url: https://sources.com/sources:11001
- push: true
- auth:
- server-cert: server.crt
- client-cert: client.crt
- client-key: client.key
+ override-project-caches: false
+ servers:
+ - url: https://sources.com/sources:11001
+ push: true
+ auth:
+ server-cert: server.crt
+ client-cert: client.crt
+ client-key: client.key
Project recommendations