api: document warnings for setting api.ClientConnTimeout (#14122)

HTTP API consumers that have network line-of-sight to client nodes can connect
directly for a small number of APIs. But in environments where the consumer
doesn't have line-of-sight, there's a long pause waiting for the
`api.ClientConnTimeout` to expire. Warn about this in the API docs so that
authors can avoid the extra timeout.

api/allocations.go

@@ -81,6 +81,10 @@ func (a *Allocations) Info(allocID string, q *QueryOptions) (*Allocation, *Query
 // * terminalSizeCh: A channel to send new tty terminal sizes
 //
 // The call blocks until command terminates (or an error occurs), and returns the exit code.
+//
+// Note: for cluster topologies where API consumers don't have network access to
+// Nomad clients, set api.ClientConnTimeout to a small value (ex 1ms) to avoid
+// long pauses on this API call.
 func (a *Allocations) Exec(ctx context.Context,
 	alloc *Allocation, task string, tty bool, command []string,
 	stdin io.Reader, stdout, stderr io.Writer,
@@ -104,18 +108,33 @@ func (a *Allocations) Exec(ctx context.Context,
 	return s.run(ctx)
 }
 
+// Stats gets allocation resource usage statistics about an allocation.
+//
+// Note: for cluster topologies where API consumers don't have network access to
+// Nomad clients, set api.ClientConnTimeout to a small value (ex 1ms) to avoid
+// long pauses on this API call.
 func (a *Allocations) Stats(alloc *Allocation, q *QueryOptions) (*AllocResourceUsage, error) {
 	var resp AllocResourceUsage
 	_, err := a.client.query("/v1/client/allocation/"+alloc.ID+"/stats", &resp, q)
 	return &resp, err
 }
 
+// GC forces a garbage collection of client state for an allocation.
+//
+// Note: for cluster topologies where API consumers don't have network access to
+// Nomad clients, set api.ClientConnTimeout to a small value (ex 1ms) to avoid
+// long pauses on this API call.
 func (a *Allocations) GC(alloc *Allocation, q *QueryOptions) error {
 	var resp struct{}
 	_, err := a.client.query("/v1/client/allocation/"+alloc.ID+"/gc", &resp, nil)
 	return err
 }
 
+// Restart restarts an allocation.
+//
+// Note: for cluster topologies where API consumers don't have network access to
+// Nomad clients, set api.ClientConnTimeout to a small value (ex 1ms) to avoid
+// long pauses on this API call.
 func (a *Allocations) Restart(alloc *Allocation, taskName string, q *QueryOptions) error {
 	req := AllocationRestartRequest{
 		TaskName: taskName,
@@ -126,6 +145,11 @@ func (a *Allocations) Restart(alloc *Allocation, taskName string, q *QueryOption
 	return err
 }
 
+// Stop stops an allocation.
+//
+// Note: for cluster topologies where API consumers don't have network access to
+// Nomad clients, set api.ClientConnTimeout to a small value (ex 1ms) to avoid
+// long pauses on this API call.
 func (a *Allocations) Stop(alloc *Allocation, q *QueryOptions) (*AllocStopResponse, error) {
 	var resp AllocStopResponse
 	_, err := a.client.putQuery("/v1/allocation/"+alloc.ID+"/stop", nil, &resp, q)
@@ -140,6 +164,11 @@ type AllocStopResponse struct {
 	WriteMeta
 }
 
+// Signal sends a signal to the allocation.
+//
+// Note: for cluster topologies where API consumers don't have network access to
+// Nomad clients, set api.ClientConnTimeout to a small value (ex 1ms) to avoid
+// long pauses on this API call.
 func (a *Allocations) Signal(alloc *Allocation, q *QueryOptions, task, signal string) error {
 	req := AllocSignalRequest{
 		Signal: signal,

api/api.go

@@ -25,7 +25,9 @@ import (
 var (
 	// ClientConnTimeout is the timeout applied when attempting to contact a
 	// client directly before switching to a connection through the Nomad
-	// server.
+	// server. For cluster topologies where API consumers don't have network
+	// access to Nomad clients, set this to a small value (ex 1ms) to avoid
+	// pausing on client APIs such as AllocFS.
 	ClientConnTimeout = 1 * time.Second
 )
 

api/fs.go

@@ -51,7 +51,10 @@ func (c *Client) AllocFS() *AllocFS {
 	return &AllocFS{client: c}
 }
 
-// List is used to list the files at a given path of an allocation directory
+// List is used to list the files at a given path of an allocation directory.
+// Note: for cluster topologies where API consumers don't have network access to
+// Nomad clients, set api.ClientConnTimeout to a small value (ex 1ms) to avoid
+// long pauses on this API call.
 func (a *AllocFS) List(alloc *Allocation, path string, q *QueryOptions) ([]*AllocFileInfo, *QueryMeta, error) {
 	if q == nil {
 		q = &QueryOptions{}
@@ -70,7 +73,10 @@ func (a *AllocFS) List(alloc *Allocation, path string, q *QueryOptions) ([]*Allo
 	return resp, qm, nil
 }
 
-// Stat is used to stat a file at a given path of an allocation directory
+// Stat is used to stat a file at a given path of an allocation directory.
+// Note: for cluster topologies where API consumers don't have network access to
+// Nomad clients, set api.ClientConnTimeout to a small value (ex 1ms) to avoid
+// long pauses on this API call.
 func (a *AllocFS) Stat(alloc *Allocation, path string, q *QueryOptions) (*AllocFileInfo, *QueryMeta, error) {
 	if q == nil {
 		q = &QueryOptions{}
@@ -91,6 +97,9 @@ func (a *AllocFS) Stat(alloc *Allocation, path string, q *QueryOptions) (*AllocF
 
 // ReadAt is used to read bytes at a given offset until limit at the given path
 // in an allocation directory. If limit is <= 0, there is no limit.
+// Note: for cluster topologies where API consumers don't have network access to
+// Nomad clients, set api.ClientConnTimeout to a small value (ex 1ms) to avoid
+// long pauses on this API call.
 func (a *AllocFS) ReadAt(alloc *Allocation, path string, offset int64, limit int64, q *QueryOptions) (io.ReadCloser, error) {
 	reqPath := fmt.Sprintf("/v1/client/fs/readat/%s", alloc.ID)
 
@@ -103,7 +112,10 @@ func (a *AllocFS) ReadAt(alloc *Allocation, path string, offset int64, limit int
 }
 
 // Cat is used to read contents of a file at the given path in an allocation
-// directory
+// directory.
+// Note: for cluster topologies where API consumers don't have network access to
+// Nomad clients, set api.ClientConnTimeout to a small value (ex 1ms) to avoid
+// long pauses on this API call.
 func (a *AllocFS) Cat(alloc *Allocation, path string, q *QueryOptions) (io.ReadCloser, error) {
 	reqPath := fmt.Sprintf("/v1/client/fs/cat/%s", alloc.ID)
 	return queryClientNode(a.client, alloc, reqPath, q,
@@ -120,6 +132,10 @@ func (a *AllocFS) Cat(alloc *Allocation, path string, q *QueryOptions) (io.ReadC
 // * cancel: A channel that when closed, streaming will end.
 //
 // The return value is a channel that will emit StreamFrames as they are read.
+//
+// Note: for cluster topologies where API consumers don't have network access to
+// Nomad clients, set api.ClientConnTimeout to a small value (ex 1ms) to avoid
+// long pauses on this API call.
 func (a *AllocFS) Stream(alloc *Allocation, path, origin string, offset int64,
 	cancel <-chan struct{}, q *QueryOptions) (<-chan *StreamFrame, <-chan error) {
 
@@ -224,6 +240,10 @@ func queryClientNode(c *Client, alloc *Allocation, reqPath string, q *QueryOptio
 // reached.
 //
 // Unexpected (non-EOF) errors will be sent on the error chan.
+//
+// Note: for cluster topologies where API consumers don't have network access to
+// Nomad clients, set api.ClientConnTimeout to a small value (ex 1ms) to avoid
+// long pauses on this API call.
 func (a *AllocFS) Logs(alloc *Allocation, follow bool, task, logType, origin string,
 	offset int64, cancel <-chan struct{}, q *QueryOptions) (<-chan *StreamFrame, <-chan error) {