Merge pull request #9804 from circleci/onprem-2442/update-howto-access-external-nomad-ui

ONPREM-2442 | Access Nomad UI when using External Nomad Servers

Author: rosieyohannan

docs/server-admin-4.8/modules/operator/pages/introduction-to-nomad-cluster-operation.adoc

@@ -15,7 +15,7 @@ image::guides:ROOT:nomad-diagram-v2.png[Diagram of the Nomad cluster]
 
 - **Nomad client:** Nomad clients execute the jobs they are allocated by Nomad servers. Usually a Nomad client runs on a dedicated machine (often a VM) to take full advantage of machine power. You can have multiple Nomad clients to form a cluster and the Nomad server allocates jobs to the cluster with its scheduling algorithm.
 
-- **Nomad jobs:** A Nomad job is a specification, provided by a user, that declares a workload for Nomad. A Nomad job corresponds to an execution of a CircleCI job. If the job uses xref:guides:optimize:parallelism-faster-jobs.adoc#[parallelism], for example `parallelism: 10`, then Nomad runs 10 jobs.
+- **Nomad jobs:** A Nomad job is a specification, provided by a user, that declares a workload for Nomad. A Nomad job corresponds to an execution of a CircleCI job. If the job uses parallelism, for example `parallelism: 10`, then Nomad runs 10 jobs. For more information on parallelism, see the xref:guides:optimize:parallelism-faster-jobs.adoc#[Test Splitting and Parallelism] guide.
 
 - **Build agent:** Build agent is a Go program written by CircleCI that executes steps in a job and reports the results. Build agent is executed as the main process inside a Nomad job.
 
@@ -31,9 +31,9 @@ The `nomad` CLI is installed in the Nomad pod. It is preconfigured to talk to th
 
 The get a list of statuses for all jobs in your cluster, run the following command:
 
-[source,shell]
+[source,console]
 ----
-kubectl exec -it <nomad-server-pod-ID> -- nomad status
+$ kubectl exec -it <nomad-server-pod-ID> -- nomad status
 ----
 
 The `Status` is the most important field in the output, with the following status type definitions:
@@ -49,18 +49,18 @@ The `Status` is the most important field in the output, with the following statu
 
 To get a list of your Nomad clients, run the following command:
 
-[source,shell]
+[source,console]
 ----
-kubectl exec -it <nomad-server-pod-ID> -- nomad node-status
+$ kubectl exec -it <nomad-server-pod-ID> -- nomad node-status
 ----
 
 NOTE: `nomad node-status` reports both Nomad clients that are currently serving (status `active`) and Nomad clients that were taken out of the cluster (status `down`). Therefore, you need to count the number of `active` Nomad clients to know the current capacity of your cluster.
 
 To get more information about a specific client, run the following command from that client:
 
-[source,shell]
+[source,console]
 ----
-kubectl exec -it <nomad-server-pod-ID> -- nomad node-status -self
+$ kubectl exec -it <nomad-server-pod-ID> -- nomad node-status -self
 ----
 
 This gives information such as how many jobs are running on the client and the resource utilization of the client.
@@ -70,9 +70,9 @@ This gives information such as how many jobs are running on the client and the r
 
 A Nomad job corresponds to an execution of a CircleCI job. Therefore, Nomad job logs can sometimes help to understand the status of a CircleCI job if there is a problem. To get logs for a specific job, run the following command:
 
-[source,shell]
+[source,console]
 ----
-kubectl exec -it <nomad-server-pod-ID> -- nomad logs -job -stderr <nomad-job-id>
+$ kubectl exec -it <nomad-server-pod-ID> -- nomad logs -job -stderr <nomad-job-id>
 ----
 
 NOTE: Be sure to specify the `-stderr` flag, as this is where most Build Agent logs appear.
@@ -83,30 +83,37 @@ Complete the following steps to get logs from the allocation of the specified jo
 
 . Get the job ID with `nomad status` command.
 . Get the allocation ID of the job with `nomad status <job-id>` command.
-. Get the logs from the allocation with `nomad logs -stderr <allocation-id>`
+. Get the logs from the allocation with `nomad logs -stderr <allocation-id>`.
 
 [#accessing-the-nomad-web-ui]
 === Accessing the Nomad Web UI
 
 Nomad provides a web UI for inspecting your Nomad cluster. If you are using an internalized Nomad deployment, which is the default setup with CircleCI server, follow the instructions in this section to temporarily access the UI for troubleshooting purposes. For a more permanent solution, consider externalizing Nomad and consult the official Nomad documentation for setting up routing.
 
-. Nomad binds to its Pod IP. To port-forward to the Nomad service, you need to set up a lightweight tunneling mechanism within the cluster as follows:
+. When using Nomad in Kubernetes, it binds to its Pod IP address. Use the command below to fetch the IP address of the Nomad server:
 +
-[source,bash]
+[source,console]
 ----
-export NOMAD_IP=$(kubectl get svc nomad-server -o jsonpath='{.spec.clusterIP}' -n <server-namespace>)
+$ export NOMAD_ADDR=$(kubectl get svc nomad-server -o jsonpath='{.spec.clusterIP}' -n <server-namespace>)
+----
+
+. If using Externalized Nomad, Use Nomad Network Load Balancer or DNS address to port-forward to access the web UI.
 
-kubectl run nomad-tunnel --rm -it --restart=Never --image=alpine/socat -n <server-namespace> -- TCP-LISTEN:4646,fork,reuseaddr TCP:$NOMAD_IP:4646
+. To port-forward to the Nomad service, set up a lightweight tunnelling mechanism within the cluster as follows:
++
+[source,console]
+----
+$ kubectl run nomad-tunnel --rm -it --restart=Never --image=alpine/socat -n <server-namespace> -- TCP-LISTEN:4646,fork,reuseaddr TCP:$NOMAD_ADDR:4646
 ----
 
 . In another terminal, run the following command to set up port forwarding:
 +
-[source,bash]
+[source,console]
 ----
-kubectl port-forward pod/nomad-tunnel 4646:4646 -n <server-namespace>
+$ kubectl port-forward pod/nomad-tunnel 4646:4646 -n <server-namespace>
 ----
 
-. Navigate to ++`http://localhost:4646/ui`++ in your browser to access the Nomad UI. For more information on utilizing the Nomad UI, refer to the link:https://developer.hashicorp.com/nomad/tutorials/web-ui[Nomad documentation].
+. Navigate to `++http[s]://localhost:4646/ui++` in your browser to access the Nomad UI. For more information on utilizing the Nomad UI, refer to the link:https://developer.hashicorp.com/nomad/tutorials/web-ui[Nomad documentation].
 
 [#shutting-down-a-nomad-client]
 === Shutting down a Nomad client
@@ -115,22 +122,22 @@ When you want to shut down a Nomad client, you must first set the client to `dra
 
 . To drain a client, log in to the client and set the client to drain mode with `node-drain` command as follows:
 +
-[source,shell]
+[source,console]
 ----
-nomad node-drain -self -enable
+$ nomad node-drain -self -enable
 ----
 . Then, make sure the client is in drain mode using the `node-status` command:
 +
-[source,shell]
+[source,console]
 ----
-nomad node-status -self
+$ nomad node-status -self
 ----
 
 Alternatively, you can drain a remote node with the following command, substituting the node ID:
 
-[source,shell]
+[source,console]
 ----
-nomad node-drain -enable -yes <node-id>
+$ nomad node-drain -enable -yes <node-id>
 ----
 
 [#scaling-down-the-client-cluster]
@@ -145,7 +152,7 @@ The script should use the commands in the section above to do the following:
 . Terminate the instance.
 
 [#externalize-servers]
-== Externalize your Nomad Servers
+== Externalize your Nomad servers
 From server v4.8, Nomad Servers may now be deployed externally to your Kubernetes cluster that hosts your installation of CircleCI server. Externalization of Nomad Servers is optional. Externalization of Nomad Servers can improve their stability. If you already have a CircleCI server instance with _internal_ Nomad Servers, the process to switch to external Nomad Servers is as follows:
 
 . Stop all builds on your CircleCI server instance.
@@ -155,5 +162,5 @@ ifndef::pdf[]
 [#next-steps]
 == Next steps
 
-* Read the xref:managing-user-accounts.adoc#[Managing user accounts] guide.
+* Read the xref:managing-user-accounts.adoc#[Managing User Accounts] guide.
 endif::[]

styles/circleci-docs/ListPunctuation.yml

@@ -1,8 +1,8 @@
 extends: existence
-message: "List items should end with a period (unless it's a single word or URL)."
+message: "List items should end with a period or colon (unless it's a single word or URL)."
 link: https://github.com/circleci/circleci-docs
 scope: list
 level: error
 raw:
-  # Match items with at least 2 words that don't end with period or URL
-  - '\S+\s+\S+.*[^.\s/]\s*$'
+  # Match items with at least 2 words that don't end with period, colon, or URL
+  - '\S+\s+\S+.*[^.\s/:]\s*$'