Merge pull request #8334 from hashicorp/docs-all-namespaces-queries

Document namespace flag and API parameter

command/meta.go

@@ -177,6 +177,8 @@ func generalOptionsUsage() string {
   -namespace=<namespace>
     The target namespace for queries and actions bound to a namespace.
     Overrides the NOMAD_NAMESPACE environment variable if set.
+    If set to '*', job and alloc subcommands query all namespacecs authorized
+    to user.
     Defaults to the "default" namespace.
 
   -no-color

website/pages/api-docs/allocations.mdx

@@ -32,6 +32,9 @@ The table below shows this endpoint's support for
   even number of hexadecimal characters (0-9a-f). This is specified as a query
   string parameter.
 
+- `namespace` `(string: "default")` - Specifies the namespace to search. Specifying
+  `*` would return all allocations across all the authorized namespaces.
+
 ### Sample Request
 
 ```shell-session
@@ -44,6 +47,11 @@ $ curl \
     https://localhost:4646/v1/allocations?prefix=a8198d79
 ```
 
+```shell-session
+$ curl \
+    https://localhost:4646/v1/allocations?namespace=*&prefix=a8198d79
+```
+
 ### Sample Response
 
 ```json

website/pages/api-docs/index.mdx

@@ -90,6 +90,17 @@ $ curl \
     https://localhost:4646/v1/jobs
 ```
 
+## Namespaces
+
+Nomad Enterprise has support for namespaces, which allow jobs and their associated objects to be segmented from each other and other users of the cluster.  When using non-default namespace, the API request must pass the target namespace as an API query parameter.
+
+Here is an example using curl:
+
+```shell-session
+$ curl \
+    https://localhost:4646/v1/jobs?namespace=qa
+```
+
 ## Blocking Queries
 
 Many endpoints in Nomad support a feature known as "blocking queries". A

website/pages/api-docs/jobs.mdx

@@ -30,6 +30,9 @@ The table below shows this endpoint's support for
 - `prefix` `(string: "")` - Specifies a string to filter jobs on based on
   an index prefix. This is specified as a query string parameter.
 
+- `namespace` `(string: "default")` - Specifies the target namespace. Specifying
+  `*` would return all jobs across all the authorized namespaces.
+
 ### Sample Request
 
 ```shell-session
@@ -40,6 +43,10 @@ $ curl https://localhost:4646/v1/jobs
 $ curl https://localhost:4646/v1/jobs?prefix=team
 ```
 
+```shell-session
+$ curl https://localhost:4646/v1/jobs?namespace=*&prefix=team
+```
+
 ### Sample Response
 
 ```json

website/pages/partials/general_options.mdx

@@ -5,6 +5,11 @@
   Overrides the `NOMAD_REGION` environment variable if set. Defaults to the
   Agent's local region.
 
+- `-namespace=<namespace>`: The target namespace for queries and actions bound
+  to a namespace. Overrides the NOMAD_NAMESPACE environment variable if set.
+  If set to '*', job and alloc subcommands query all namespacecs authorized to
+  user. Defaults to the "default" namespace.
+
 - `-no-color`: Disables colored command output. Alternatively,
   `NOMAD_CLI_NO_COLOR` may be set.