diff options
author | richardmaw-codethink <richard.maw@codethink.co.uk> | 2018-11-07 11:32:20 +0000 |
---|---|---|
committer | richardmaw-codethink <richard.maw@codethink.co.uk> | 2018-11-07 11:32:20 +0000 |
commit | 029ba17dd7c4f5cd2f7180e9252fdd5376143816 (patch) | |
tree | 5b9c259ef5dac3c416c000171b6e8815aca07ef1 | |
parent | 1f7acf748babea91909489d696ce1dcce2232f60 (diff) | |
parent | f514124fc6045b7df7e786940684040c187cc581 (diff) | |
download | buildstream-029ba17dd7c4f5cd2f7180e9252fdd5376143816.tar.gz |
Merge branch 'jennis/docs_patch' into 'master'
Update our instructions/examples regarding how we declare remote caches
See merge request BuildStream/buildstream!932
-rw-r--r-- | doc/source/format_project.rst | 25 | ||||
-rw-r--r-- | doc/source/using_config.rst | 67 | ||||
-rw-r--r-- | doc/source/using_configuring_artifact_server.rst | 56 |
3 files changed, 81 insertions, 67 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 <artifacts>` 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 <server_authentication>`. -You can also specify a list of caches here; earlier entries in the list -will have higher priority than later ones. Remote execution ~~~~~~~~~~~~~~~~ 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 -<artifacts>` 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 <artifacts>` 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 <server_authentication>`. -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..cc4880e94 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 ~~~~~~~~~~~~~~~~~~~~~~~ @@ -237,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 <https://www.devdungeon.com/content/creating-systemd-service-files>`_. -User configuration -~~~~~~~~~~~~~~~~~~ -The user configuration for artifacts is documented with the rest -of the :ref:`user configuration documentation <user_config>`. - -Note that for self-signed certificates, the public key fields are mandatory. - -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 +Declaring remote artifact caches +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Remote artifact caches can be declared within either: -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:: +1. The :ref:`project configuration <project_essentials_artifacts>`, or +2. The :ref:`user configuration <config_artifacts>`. - 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. |