From 8e64ccefcbfcaa8ea0cd194a279c19d8b22a7df1 Mon Sep 17 00:00:00 2001 From: James Ennis Date: Tue, 6 Nov 2018 15:39:36 +0000 Subject: using_config.rst: Update our instructions for how we declare caches in user config --- doc/source/using_config.rst | 67 ++++++++++++++++++------ doc/source/using_configuring_artifact_server.rst | 2 + 2 files changed, 54 insertions(+), 15 deletions(-) diff --git a/doc/source/using_config.rst b/doc/source/using_config.rst index c707cd04b..8835c23db 100644 --- a/doc/source/using_config.rst +++ b/doc/source/using_config.rst @@ -32,38 +32,75 @@ the supported configurations on a project wide basis are listed here. Artifact server ~~~~~~~~~~~~~~~ -The project you build will often specify a :ref:`remote artifact cache -` already, but you may want to specify extra caches. There are two -ways to do this. You can add one or more global caches: +Although project's often specify a :ref:`remote artifact cache ` in +their ``project.conf``, you may also want to specify extra caches. -**Example** +Assuming that your host/server is reachable on the internet as ``artifacts.com`` +(for example), there are two ways to declare remote caches in your user +configuration: + +1. Adding global caches: .. code:: yaml + # + # Artifacts + # artifacts: - url: https://artifacts.com/artifacts + # Add a cache to pull from + - url: https://artifacts.com/artifacts:11001 + server-cert: server.crt + # Add a cache to push/pull to/from + - url: https://artifacts.com/artifacts:11002 + server-cert: server.crt + client-cert: client.crt + client-key: client.key + push: true + # Add another cache to pull from + - url: https://anothercache.com/artifacts:8080 + server-cert: another_server.crt + +.. note:: -Caches listed there will be considered lower priority than those specified -by the project configuration. + Caches declared here will be used by **all** BuildStream project's on the user's + machine and are considered a lower priority than those specified in the project + configuration. -You can also add project-specific caches: -**Example** +2. Specifying caches for a specific project within the user configuration: .. code:: yaml projects: project-name: artifacts: - - url: https://artifacts.com/artifacts1 - - url: ssh://user@artifacts.com/artifacts2 + # Add a cache to pull from + - url: https://artifacts.com/artifacts:11001 + server-cert: server.crt + # Add a cache to push/pull to/from + - url: https://artifacts.com/artifacts:11002 + server-cert: server.crt + client-cert: client.crt + client-key: client.key push: true + # Add another cache to pull from + - url: https://ourprojectcache.com/artifacts:8080 + server-cert: project_server.crt + + +.. note:: + + Caches listed here will be considered a higher priority than those specified + by the project. Furthermore, for a given list of URLs, earlier entries will + have higher priority. + + +Notice that the use of different ports for the same server distinguishes between +pull only access and push/pull access. For information regarding this and the +server/client certificates and keys, please see: +:ref:`Key pair for the server `. -Caches listed here will be considered higher priority than those specified -by the project. -If you give a list of URLs, earlier entries in the list will have higher -priority than later ones. Strict build plan ~~~~~~~~~~~~~~~~~ diff --git a/doc/source/using_configuring_artifact_server.rst b/doc/source/using_configuring_artifact_server.rst index dd727ceb8..e3f2f6af9 100644 --- a/doc/source/using_configuring_artifact_server.rst +++ b/doc/source/using_configuring_artifact_server.rst @@ -98,6 +98,8 @@ Command reference :prog: bst-artifact-server +.. _server_authentication: + Key pair for the server ~~~~~~~~~~~~~~~~~~~~~~~ -- cgit v1.2.1 From 09ab676d0567032a4716f32c8c07cb1dbf0a02f5 Mon Sep 17 00:00:00 2001 From: James Ennis Date: Tue, 6 Nov 2018 16:14:10 +0000 Subject: format_project.rst: Update instructions regarding how we declare remote caches in project.conf --- doc/source/format_project.rst | 25 ++++++++++++++++++++----- 1 file changed, 20 insertions(+), 5 deletions(-) diff --git a/doc/source/format_project.rst b/doc/source/format_project.rst index 469f99747..8701facb0 100644 --- a/doc/source/format_project.rst +++ b/doc/source/format_project.rst @@ -190,19 +190,34 @@ for more detail. Artifact server ~~~~~~~~~~~~~~~ If you have setup an :ref:`artifact server ` for your -project then it is convenient to configure this in your ``project.conf`` +project then it is convenient to configure the following in your ``project.conf`` so that users need not have any additional configuration to communicate with an artifact share. .. code:: yaml + # + # Artifacts + # artifacts: + # A remote cache from which to download prebuilt artifacts + - url: https://foo.com/artifacts:11001 + server.cert: server.crt + # A remote cache from which to upload/download built/prebuilt artifacts + - url: https://foo.com/artifacts:11002 + server-cert: server.crt + client-cert: client.crt + client-key: client.key - # A url from which to download prebuilt artifacts - url: https://foo.com/artifacts +.. note:: + + You can also specify a list of different caches here; earlier entries in the + list will have higher priority than later ones. + +The use of ports are required to distinguish between pull only access and +push/pull access. For information regarding the server/client certificates +and keys, please see: :ref:`Key pair for the server `. -You can also specify a list of caches here; earlier entries in the list -will have higher priority than later ones. Remote execution ~~~~~~~~~~~~~~~~ -- cgit v1.2.1 From f514124fc6045b7df7e786940684040c187cc581 Mon Sep 17 00:00:00 2001 From: James Ennis Date: Tue, 6 Nov 2018 16:15:36 +0000 Subject: using_configuring_artifact_server.rst: Remove examples and redirect to user config/project config --- doc/source/using_configuring_artifact_server.rst | 54 +++--------------------- 1 file changed, 7 insertions(+), 47 deletions(-) diff --git a/doc/source/using_configuring_artifact_server.rst b/doc/source/using_configuring_artifact_server.rst index e3f2f6af9..cc4880e94 100644 --- a/doc/source/using_configuring_artifact_server.rst +++ b/doc/source/using_configuring_artifact_server.rst @@ -239,52 +239,12 @@ We can then check if the services are successfully running with: For more information on systemd services see: `Creating Systemd Service Files `_. -User configuration -~~~~~~~~~~~~~~~~~~ -The user configuration for artifacts is documented with the rest -of the :ref:`user configuration documentation `. +Declaring remote artifact caches +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Remote artifact caches can be declared within either: -Note that for self-signed certificates, the public key fields are mandatory. +1. The :ref:`project configuration `, or +2. The :ref:`user configuration `. -Assuming you have the same setup used in this document, and that your -host is reachable on the internet as ``artifacts.com`` (for example), -then a user can use the following user configuration: - -Pull-only: - -.. code:: yaml - - # - # Artifacts - # - artifacts: - - url: https://artifacts.com:11001 - - # Optional server certificate if not trusted by system root certificates - server-cert: server.crt - -Pull and push: - -.. code:: yaml - - # - # Artifacts - # - artifacts: - - url: https://artifacts.com:11002 - - # Optional server certificate if not trusted by system root certificates - server-cert: server.crt - - # Optional client key pair for authentication - client-key: client.key - client-cert: client.crt - - push: true - -.. note:: - - Equivalent statements can be delcared in a project's configuration file - (the ``project.conf``). +Please follow the above links to see examples showing how we declare remote +caches in both the project configuration and the user configuration, respectively. -- cgit v1.2.1