client: Allow fetching the env from the coordinator

Remote users have to keep a local copy of the lab env file in sync with
the coordinator before they can run labgrid-client against it.  This is
friction for casual workflows like triage or console access from a
laptop, and is awkward to maintain across many client machines.

Provide a way for clients to fetch the env from the coordinator on
startup.  Setting LG_ENV (or --config) to the literal string
'coordinator:' issues a one-shot GetEnvironment RPC against the
coordinator.  The returned YAML is written under $XDG_CACHE_HOME/labgrid
(or ~/.cache/labgrid) and loaded exactly as if the user had pointed at a
local file, so the rest of the client is untouched.  The cache file is
overwritten on each fetch so users can inspect what env the client just
loaded.  Remote users then only need labgrid, network access to the
coordinator and three environment variables (PATH, LG_COORDINATOR,
LG_ENV=coordinator:) to run labgrid-client console -p <board> from
anywhere.

Per-user paths inside the served env (build dirs, log dirs, source
trees) are still resolvable via the existing LG_* template substitution,
so individual clients can override only the few values that matter to
them without forking the env file.

The coordinator address used for the fetch comes from --coordinator on
the command line if given, otherwise LG_COORDINATOR, with
127.0.0.1:20408 as the final default - matching the fallback chain
main() uses elsewhere.

Signed-off-by: Simon Glass <sjg@chromium.org>

Author: sjg20

doc/man/client.rst

@@ -49,6 +49,15 @@ LG_ENV
 This variable can be used to specify the configuration file to use without
 using the ``--config`` option, the ``--config`` option overrides it.
 
+The special value ``coordinator:`` (or ``--config coordinator:``) tells the
+client to fetch the environment from the coordinator over the ``GetEnvironment``
+RPC instead of reading a local file, which is useful when working from a remote
+machine that does not have the lab env file available locally.  The fetched
+YAML is cached under ``$XDG_CACHE_HOME/labgrid/env.cfg`` (or
+``~/.cache/labgrid/env.cfg``) so it can be inspected after the fact.  The
+coordinator must have been started with ``--environment``; see
+``labgrid-coordinator``\(1).
+
 LG_COORDINATOR
 ~~~~~~~~~~~~~~
 This variable can be used to set the default coordinator in the format

doc/usage.rst

@@ -166,6 +166,37 @@ allocated before returning.
 A reservation will time out after a short time, if it is neither refreshed nor
 used by locked places.
 
+Fetching the Environment from the Coordinator
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When several developers (or CI jobs) share a lab, distributing the env file out
+of band - via a shared filesystem, git checkout or scp - is awkward duplication.
+``labgrid-coordinator`` can serve a curated env to clients on demand, so a
+remote user only needs network access to the coordinator and a labgrid install.
+
+Start the coordinator with ``--environment`` pointing at a YAML file:
+
+.. code-block:: bash
+
+   $ labgrid-coordinator --environment /etc/labgrid/lab.cfg
+
+On the client side, set ``LG_ENV=coordinator:`` (or ``--config coordinator:``)
+to fetch the env via the ``GetEnvironment`` RPC instead of reading a local file.
+The returned YAML is cached under ``$XDG_CACHE_HOME/labgrid/env.cfg`` (or
+``~/.cache/labgrid/env.cfg``), overwritten on each fetch so a user can inspect
+what env the client just loaded.
+
+.. code-block:: bash
+
+   $ export LG_COORDINATOR=lab-host:20408
+   $ export LG_ENV=coordinator:
+   $ labgrid-client console -p <board>
+
+Per-user paths inside the served env (build dirs, log dirs, source trees) are
+still resolvable via the existing ``LG_*`` template substitution, so individual
+clients can override only the few values that matter to them without forking the
+env file.
+
 Library
 -------
 labgrid can be used directly as a Python library, without the infrastructure

labgrid/remote/client.py

@@ -1725,6 +1725,39 @@ def start_session(
     return session
 
 
+def fetch_coordinator_environment(address):
+    """Fetch the env file served by the coordinator and cache it on disk
+
+    Used when the user sets ``LG_ENV=coordinator:`` (or
+    ``--config coordinator:``) instead of pointing at a local file.
+
+    Returns the path to the cached file (under ``$XDG_CACHE_HOME`` or
+    ``~/.cache/labgrid/env.cfg``), overwritten on each call so users
+    can inspect what env the client just loaded.  Raises UserError if
+    the coordinator is not configured to serve an environment.
+    """
+    address = proxymanager.get_grpc_address(address, default_port=20408)
+    with grpc.insecure_channel(address) as channel:
+        stub = labgrid_coordinator_pb2_grpc.CoordinatorStub(channel)
+        try:
+            response = stub.GetEnvironment(
+                labgrid_coordinator_pb2.GetEnvironmentRequest(),
+                timeout=10.0,
+            )
+        except grpc.RpcError as e:
+            raise UserError(f"failed to fetch environment from coordinator at {address}: {e.details() or e}") from e
+    if not response.config:
+        raise UserError(
+            f"coordinator at {address} has no environment configured (start coordinator with --environment <file>)"
+        )
+    cache_dir = os.path.join(os.environ.get("XDG_CACHE_HOME", os.path.expanduser("~/.cache")), "labgrid")
+    os.makedirs(cache_dir, exist_ok=True)
+    path = os.path.join(cache_dir, "env.cfg")
+    with open(path, "w", encoding="utf-8") as f:
+        f.write(response.config)
+    return path
+
+
 def find_role_by_place(config, place):
     for role, role_config in config.items():
         resources, _ = target_factory.normalize_config(role_config)
@@ -2305,6 +2338,17 @@ def main():
     if args.proxy:
         proxymanager.force_proxy(args.proxy)
 
+    if args.config == "coordinator:":
+        # Fetch the env from the coordinator.  The address can't be taken from
+        # env.config yet (no env loaded), so use the same fallback chain the
+        # rest of main() uses, minus that.
+        addr = args.coordinator or os.environ.get("LG_COORDINATOR", "127.0.0.1:20408")
+        try:
+            args.config = fetch_coordinator_environment(addr)
+        except UserError as e:
+            print(e, file=sys.stderr)
+            exit(1)
+
     env = None
     if args.config:
         env = Environment(config_file=args.config)

man/labgrid-client.1

@@ -1145,6 +1145,15 @@ A desired state must be set using \fBLG_STATE\fP or \fB\-s\fP/\fB\-\-state\fP\&.
 .sp
 This variable can be used to specify the configuration file to use without
 using the \fB\-\-config\fP option, the \fB\-\-config\fP option overrides it.
+.sp
+The special value \fBcoordinator:\fP (or \fB\-\-config coordinator:\fP) tells the
+client to fetch the environment from the coordinator over the \fBGetEnvironment\fP
+RPC instead of reading a local file, which is useful when working from a remote
+machine that does not have the lab env file available locally.  The fetched
+YAML is cached under \fB$XDG_CACHE_HOME/labgrid/env.cfg\fP (or
+\fB~/.cache/labgrid/env.cfg\fP) so it can be inspected after the fact.  The
+coordinator must have been started with \fB\-\-environment\fP; see
+\fBlabgrid\-coordinator\fP(1).
 .SS LG_COORDINATOR
 .sp
 This variable can be used to set the default coordinator in the format