From e4120e34c94cb07cb2440e2d89cbc5cb4b3b9c12 Mon Sep 17 00:00:00 2001 From: Rob Genova Date: Fri, 22 Jun 2018 20:41:20 +0000 Subject: [PATCH 01/16] Re-organize existing docs and guides --- website/source/docs/{agent => }/configuration/acl.html.md | 0 website/source/docs/{agent => }/configuration/autopilot.html.md | 0 website/source/docs/{agent => }/configuration/client.html.md | 0 website/source/docs/{agent => }/configuration/consul.html.md | 0 website/source/docs/{agent => }/configuration/index.html.md | 0 website/source/docs/{agent => }/configuration/sentinel.html.md | 0 website/source/docs/{agent => }/configuration/server.html.md | 0 website/source/docs/{agent => }/configuration/server_join.html.md | 0 website/source/docs/{agent => }/configuration/telemetry.html.md | 0 website/source/docs/{agent => }/configuration/tls.html.md | 0 website/source/docs/{agent => }/configuration/vault.html.md | 0 website/source/docs/{runtime => }/schedulers.html.md | 0 website/source/{docs => guides/operations}/agent/index.html.md | 0 website/source/guides/{ => operations}/autopilot.html.md | 0 website/source/guides/{ => operations}/cluster/automatic.html.md | 0 .../source/guides/{ => operations}/cluster/bootstrapping.html.md | 0 .../agent => guides/operations/cluster}/cloud_auto_join.html.md | 0 website/source/guides/{ => operations}/cluster/manual.html.md | 0 .../operations/consul-integration}/index.html.md | 0 website/source/guides/{cluster => operations}/federation.md | 0 website/source/{docs => guides/operations}/install/index.html.md | 0 .../guides/{ => operations/monitoring}/nomad-metrics.html.md | 0 .../agent => guides/operations/monitoring}/telemetry.html.md | 0 website/source/guides/{ => operations}/node-draining.html.md | 0 website/source/guides/{ => operations}/outage.html.markdown | 0 .../source/guides/{cluster => operations}/requirements.html.md | 0 website/source/{docs => guides/operations}/upgrade/index.html.md | 0 .../{docs => guides/operations}/upgrade/upgrade-specific.html.md | 0 .../{docs => guides/operations}/vault-integration/index.html.md | 0 website/source/guides/{ => security}/acl.html.markdown | 0 website/source/{docs/agent => guides/security}/encryption.html.md | 0 website/source/guides/{ => security}/namespaces.html.markdown | 0 website/source/guides/{ => security}/quotas.html.md | 0 website/source/guides/{ => security}/securing-nomad.html.md | 0 .../source/guides/{ => security}/sentinel-policy.html.markdown | 0 website/source/guides/{ => security}/sentinel/job.html.md | 0 36 files changed, 0 insertions(+), 0 deletions(-) rename website/source/docs/{agent => }/configuration/acl.html.md (100%) rename website/source/docs/{agent => }/configuration/autopilot.html.md (100%) rename website/source/docs/{agent => }/configuration/client.html.md (100%) rename website/source/docs/{agent => }/configuration/consul.html.md (100%) rename website/source/docs/{agent => }/configuration/index.html.md (100%) rename website/source/docs/{agent => }/configuration/sentinel.html.md (100%) rename website/source/docs/{agent => }/configuration/server.html.md (100%) rename website/source/docs/{agent => }/configuration/server_join.html.md (100%) rename website/source/docs/{agent => }/configuration/telemetry.html.md (100%) rename website/source/docs/{agent => }/configuration/tls.html.md (100%) rename website/source/docs/{agent => }/configuration/vault.html.md (100%) rename website/source/docs/{runtime => }/schedulers.html.md (100%) rename website/source/{docs => guides/operations}/agent/index.html.md (100%) rename website/source/guides/{ => operations}/autopilot.html.md (100%) rename website/source/guides/{ => operations}/cluster/automatic.html.md (100%) rename website/source/guides/{ => operations}/cluster/bootstrapping.html.md (100%) rename website/source/{docs/agent => guides/operations/cluster}/cloud_auto_join.html.md (100%) rename website/source/guides/{ => operations}/cluster/manual.html.md (100%) rename website/source/{docs/service-discovery => guides/operations/consul-integration}/index.html.md (100%) rename website/source/guides/{cluster => operations}/federation.md (100%) rename website/source/{docs => guides/operations}/install/index.html.md (100%) rename website/source/guides/{ => operations/monitoring}/nomad-metrics.html.md (100%) rename website/source/{docs/agent => guides/operations/monitoring}/telemetry.html.md (100%) rename website/source/guides/{ => operations}/node-draining.html.md (100%) rename website/source/guides/{ => operations}/outage.html.markdown (100%) rename website/source/guides/{cluster => operations}/requirements.html.md (100%) rename website/source/{docs => guides/operations}/upgrade/index.html.md (100%) rename website/source/{docs => guides/operations}/upgrade/upgrade-specific.html.md (100%) rename website/source/{docs => guides/operations}/vault-integration/index.html.md (100%) rename website/source/guides/{ => security}/acl.html.markdown (100%) rename website/source/{docs/agent => guides/security}/encryption.html.md (100%) rename website/source/guides/{ => security}/namespaces.html.markdown (100%) rename website/source/guides/{ => security}/quotas.html.md (100%) rename website/source/guides/{ => security}/securing-nomad.html.md (100%) rename website/source/guides/{ => security}/sentinel-policy.html.markdown (100%) rename website/source/guides/{ => security}/sentinel/job.html.md (100%) diff --git a/website/source/docs/agent/configuration/acl.html.md b/website/source/docs/configuration/acl.html.md similarity index 100% rename from website/source/docs/agent/configuration/acl.html.md rename to website/source/docs/configuration/acl.html.md diff --git a/website/source/docs/agent/configuration/autopilot.html.md b/website/source/docs/configuration/autopilot.html.md similarity index 100% rename from website/source/docs/agent/configuration/autopilot.html.md rename to website/source/docs/configuration/autopilot.html.md diff --git a/website/source/docs/agent/configuration/client.html.md b/website/source/docs/configuration/client.html.md similarity index 100% rename from website/source/docs/agent/configuration/client.html.md rename to website/source/docs/configuration/client.html.md diff --git a/website/source/docs/agent/configuration/consul.html.md b/website/source/docs/configuration/consul.html.md similarity index 100% rename from website/source/docs/agent/configuration/consul.html.md rename to website/source/docs/configuration/consul.html.md diff --git a/website/source/docs/agent/configuration/index.html.md b/website/source/docs/configuration/index.html.md similarity index 100% rename from website/source/docs/agent/configuration/index.html.md rename to website/source/docs/configuration/index.html.md diff --git a/website/source/docs/agent/configuration/sentinel.html.md b/website/source/docs/configuration/sentinel.html.md similarity index 100% rename from website/source/docs/agent/configuration/sentinel.html.md rename to website/source/docs/configuration/sentinel.html.md diff --git a/website/source/docs/agent/configuration/server.html.md b/website/source/docs/configuration/server.html.md similarity index 100% rename from website/source/docs/agent/configuration/server.html.md rename to website/source/docs/configuration/server.html.md diff --git a/website/source/docs/agent/configuration/server_join.html.md b/website/source/docs/configuration/server_join.html.md similarity index 100% rename from website/source/docs/agent/configuration/server_join.html.md rename to website/source/docs/configuration/server_join.html.md diff --git a/website/source/docs/agent/configuration/telemetry.html.md b/website/source/docs/configuration/telemetry.html.md similarity index 100% rename from website/source/docs/agent/configuration/telemetry.html.md rename to website/source/docs/configuration/telemetry.html.md diff --git a/website/source/docs/agent/configuration/tls.html.md b/website/source/docs/configuration/tls.html.md similarity index 100% rename from website/source/docs/agent/configuration/tls.html.md rename to website/source/docs/configuration/tls.html.md diff --git a/website/source/docs/agent/configuration/vault.html.md b/website/source/docs/configuration/vault.html.md similarity index 100% rename from website/source/docs/agent/configuration/vault.html.md rename to website/source/docs/configuration/vault.html.md diff --git a/website/source/docs/runtime/schedulers.html.md b/website/source/docs/schedulers.html.md similarity index 100% rename from website/source/docs/runtime/schedulers.html.md rename to website/source/docs/schedulers.html.md diff --git a/website/source/docs/agent/index.html.md b/website/source/guides/operations/agent/index.html.md similarity index 100% rename from website/source/docs/agent/index.html.md rename to website/source/guides/operations/agent/index.html.md diff --git a/website/source/guides/autopilot.html.md b/website/source/guides/operations/autopilot.html.md similarity index 100% rename from website/source/guides/autopilot.html.md rename to website/source/guides/operations/autopilot.html.md diff --git a/website/source/guides/cluster/automatic.html.md b/website/source/guides/operations/cluster/automatic.html.md similarity index 100% rename from website/source/guides/cluster/automatic.html.md rename to website/source/guides/operations/cluster/automatic.html.md diff --git a/website/source/guides/cluster/bootstrapping.html.md b/website/source/guides/operations/cluster/bootstrapping.html.md similarity index 100% rename from website/source/guides/cluster/bootstrapping.html.md rename to website/source/guides/operations/cluster/bootstrapping.html.md diff --git a/website/source/docs/agent/cloud_auto_join.html.md b/website/source/guides/operations/cluster/cloud_auto_join.html.md similarity index 100% rename from website/source/docs/agent/cloud_auto_join.html.md rename to website/source/guides/operations/cluster/cloud_auto_join.html.md diff --git a/website/source/guides/cluster/manual.html.md b/website/source/guides/operations/cluster/manual.html.md similarity index 100% rename from website/source/guides/cluster/manual.html.md rename to website/source/guides/operations/cluster/manual.html.md diff --git a/website/source/docs/service-discovery/index.html.md b/website/source/guides/operations/consul-integration/index.html.md similarity index 100% rename from website/source/docs/service-discovery/index.html.md rename to website/source/guides/operations/consul-integration/index.html.md diff --git a/website/source/guides/cluster/federation.md b/website/source/guides/operations/federation.md similarity index 100% rename from website/source/guides/cluster/federation.md rename to website/source/guides/operations/federation.md diff --git a/website/source/docs/install/index.html.md b/website/source/guides/operations/install/index.html.md similarity index 100% rename from website/source/docs/install/index.html.md rename to website/source/guides/operations/install/index.html.md diff --git a/website/source/guides/nomad-metrics.html.md b/website/source/guides/operations/monitoring/nomad-metrics.html.md similarity index 100% rename from website/source/guides/nomad-metrics.html.md rename to website/source/guides/operations/monitoring/nomad-metrics.html.md diff --git a/website/source/docs/agent/telemetry.html.md b/website/source/guides/operations/monitoring/telemetry.html.md similarity index 100% rename from website/source/docs/agent/telemetry.html.md rename to website/source/guides/operations/monitoring/telemetry.html.md diff --git a/website/source/guides/node-draining.html.md b/website/source/guides/operations/node-draining.html.md similarity index 100% rename from website/source/guides/node-draining.html.md rename to website/source/guides/operations/node-draining.html.md diff --git a/website/source/guides/outage.html.markdown b/website/source/guides/operations/outage.html.markdown similarity index 100% rename from website/source/guides/outage.html.markdown rename to website/source/guides/operations/outage.html.markdown diff --git a/website/source/guides/cluster/requirements.html.md b/website/source/guides/operations/requirements.html.md similarity index 100% rename from website/source/guides/cluster/requirements.html.md rename to website/source/guides/operations/requirements.html.md diff --git a/website/source/docs/upgrade/index.html.md b/website/source/guides/operations/upgrade/index.html.md similarity index 100% rename from website/source/docs/upgrade/index.html.md rename to website/source/guides/operations/upgrade/index.html.md diff --git a/website/source/docs/upgrade/upgrade-specific.html.md b/website/source/guides/operations/upgrade/upgrade-specific.html.md similarity index 100% rename from website/source/docs/upgrade/upgrade-specific.html.md rename to website/source/guides/operations/upgrade/upgrade-specific.html.md diff --git a/website/source/docs/vault-integration/index.html.md b/website/source/guides/operations/vault-integration/index.html.md similarity index 100% rename from website/source/docs/vault-integration/index.html.md rename to website/source/guides/operations/vault-integration/index.html.md diff --git a/website/source/guides/acl.html.markdown b/website/source/guides/security/acl.html.markdown similarity index 100% rename from website/source/guides/acl.html.markdown rename to website/source/guides/security/acl.html.markdown diff --git a/website/source/docs/agent/encryption.html.md b/website/source/guides/security/encryption.html.md similarity index 100% rename from website/source/docs/agent/encryption.html.md rename to website/source/guides/security/encryption.html.md diff --git a/website/source/guides/namespaces.html.markdown b/website/source/guides/security/namespaces.html.markdown similarity index 100% rename from website/source/guides/namespaces.html.markdown rename to website/source/guides/security/namespaces.html.markdown diff --git a/website/source/guides/quotas.html.md b/website/source/guides/security/quotas.html.md similarity index 100% rename from website/source/guides/quotas.html.md rename to website/source/guides/security/quotas.html.md diff --git a/website/source/guides/securing-nomad.html.md b/website/source/guides/security/securing-nomad.html.md similarity index 100% rename from website/source/guides/securing-nomad.html.md rename to website/source/guides/security/securing-nomad.html.md diff --git a/website/source/guides/sentinel-policy.html.markdown b/website/source/guides/security/sentinel-policy.html.markdown similarity index 100% rename from website/source/guides/sentinel-policy.html.markdown rename to website/source/guides/security/sentinel-policy.html.markdown diff --git a/website/source/guides/sentinel/job.html.md b/website/source/guides/security/sentinel/job.html.md similarity index 100% rename from website/source/guides/sentinel/job.html.md rename to website/source/guides/security/sentinel/job.html.md From f10155f28571d98f1b3d8e477d3e69792785878b Mon Sep 17 00:00:00 2001 From: Rob Genova Date: Fri, 22 Jun 2018 20:42:58 +0000 Subject: [PATCH 02/16] Fix broken links in API docs --- website/source/api/acl-policies.html.md | 2 +- website/source/api/acl-tokens.html.md | 4 ++-- website/source/api/index.html.md | 2 +- website/source/api/json-jobs.html.md | 4 ++-- website/source/api/nodes.html.md | 4 ++-- website/source/api/operator.html.md | 4 ++-- website/source/api/sentinel-policies.html.md | 4 ++-- 7 files changed, 12 insertions(+), 12 deletions(-) diff --git a/website/source/api/acl-policies.html.md b/website/source/api/acl-policies.html.md index 40c111af8..04ba0d5c2 100644 --- a/website/source/api/acl-policies.html.md +++ b/website/source/api/acl-policies.html.md @@ -9,7 +9,7 @@ description: |- # ACL Policies HTTP API The `/acl/policies` and `/acl/policy/` endpoints are used to manage ACL policies. -For more details about ACLs, please see the [ACL Guide](/guides/acl.html). +For more details about ACLs, please see the [ACL Guide](/guides/security/acl.html). ## List Policies diff --git a/website/source/api/acl-tokens.html.md b/website/source/api/acl-tokens.html.md index 8b601214d..51eacbf62 100644 --- a/website/source/api/acl-tokens.html.md +++ b/website/source/api/acl-tokens.html.md @@ -9,13 +9,13 @@ description: |- # ACL Tokens HTTP API The `/acl/bootstrap`, `/acl/tokens`, and `/acl/token/` endpoints are used to manage ACL tokens. -For more details about ACLs, please see the [ACL Guide](/guides/acl.html). +For more details about ACLs, please see the [ACL Guide](/guides/security/acl.html). ## Bootstrap Token This endpoint is used to bootstrap the ACL system and provide the initial management token. This request is always forwarded to the authoritative region. It can only be invoked once -until a [bootstrap reset](/guides/acl.html#reseting-acl-bootstrap) is performed. +until a [bootstrap reset](/guides/security/acl.html#reseting-acl-bootstrap) is performed. | Method | Path | Produces | | ------ | ---------------------------- | -------------------------- | diff --git a/website/source/api/index.html.md b/website/source/api/index.html.md index 59ffdecb8..3c18fe811 100644 --- a/website/source/api/index.html.md +++ b/website/source/api/index.html.md @@ -75,7 +75,7 @@ administration. Several endpoints in Nomad use or require ACL tokens to operate. The token are used to authenticate the request and determine if the request is allowed based on the associated authorizations. Tokens are specified per-request by using the `X-Nomad-Token` request header set to the `SecretID` of an ACL Token. -For more details about ACLs, please see the [ACL Guide](/guides/acl.html). +For more details about ACLs, please see the [ACL Guide](/guides/security/acl.html). ## Authentication diff --git a/website/source/api/json-jobs.html.md b/website/source/api/json-jobs.html.md index e5f169161..4d4db1228 100644 --- a/website/source/api/json-jobs.html.md +++ b/website/source/api/json-jobs.html.md @@ -197,7 +197,7 @@ The `Job` object supports the following keys: - `Type` - Specifies the job type and switches which scheduler is used. Nomad provides the `service`, `system` and `batch` schedulers, and defaults to `service`. To learn more about each scheduler type visit - [here](/docs/runtime/schedulers.html) + [here](/docs/schedulers.html) - `Update` - Specifies an update strategy to be applied to all task groups within the job. When specified both at the job level and the task group level, @@ -366,7 +366,7 @@ The `Task` object supports the following keys: Consul for service discovery. A `Service` object represents a routable and discoverable service on the network. Nomad automatically registers when a task is started and de-registers it when the task transitions to the dead state. - [Click here](/docs/service-discovery/index.html) to learn more about + [Click here](/guides/operations/consul-integration/index.html#service-discovery) to learn more about services. Below is the fields in the `Service` object: - `Name`: An explicit name for the Service. Nomad will replace `${JOB}`, diff --git a/website/source/api/nodes.html.md b/website/source/api/nodes.html.md index 1cf87d047..9b718a781 100644 --- a/website/source/api/nodes.html.md +++ b/website/source/api/nodes.html.md @@ -759,8 +759,8 @@ $ curl \ This endpoint toggles the drain mode of the node. When draining is enabled, no further allocations will be assigned to this node, and existing allocations will -be migrated to new nodes. See the [Decommissioning Nodes -guide](/guides/node-draining.html) for suggested usage. +be migrated to new nodes. See the [Workload Migration +Guide](/guides/operations/node-draining.html) for suggested usage. | Method | Path | Produces | | ------- | ------------------------- | -------------------------- | diff --git a/website/source/api/operator.html.md b/website/source/api/operator.html.md index a172af948..2f3f69dc9 100644 --- a/website/source/api/operator.html.md +++ b/website/source/api/operator.html.md @@ -14,7 +14,7 @@ as interacting with the Raft subsystem. ~> Use this interface with extreme caution, as improper use could lead to a Nomad outage and even loss of data. -See the [Outage Recovery](/guides/outage.html) guide for some examples of how +See the [Outage Recovery](/guides/operations/outage.html) guide for some examples of how these capabilities are used. For a CLI to perform these operations manually, please see the documentation for the [`nomad operator`](/docs/commands/operator.html) command. @@ -164,7 +164,7 @@ $ curl \ ``` For more information about the Autopilot configuration options, see the -[agent configuration section](/docs/agent/configuration/autopilot.html). +[agent configuration section](/docs/configuration/autopilot.html). ## Update Autopilot Configuration diff --git a/website/source/api/sentinel-policies.html.md b/website/source/api/sentinel-policies.html.md index 4b3088836..d7c2283c4 100644 --- a/website/source/api/sentinel-policies.html.md +++ b/website/source/api/sentinel-policies.html.md @@ -9,9 +9,9 @@ description: |- # Sentinel Policies HTTP API The `/sentinel/policies` and `/sentinel/policy/` endpoints are used to manage Sentinel policies. -For more details about Sentinel policies, please see the [Sentinel Policy Guide](/guides/sentinel-policy.html). +For more details about Sentinel policies, please see the [Sentinel Policy Guide](/guides/security/sentinel-policy.html). -Sentinel endpoints are only available when ACLs are enabled. For more details about ACLs, please see the [ACL Guide](/guides/acl.html). +Sentinel endpoints are only available when ACLs are enabled. For more details about ACLs, please see the [ACL Guide](/guides/security/acl.html). ~> **Enterprise Only!** This API endpoint and functionality only exists in Nomad Enterprise. This is not present in the open source version of Nomad. From 0be66f4de13a93852a3d8cf084da1f29f7a09e69 Mon Sep 17 00:00:00 2001 From: Rob Genova Date: Fri, 22 Jun 2018 20:44:39 +0000 Subject: [PATCH 03/16] Minor updates to intro and vs. content; update use cases --- .../intro/getting-started/next-steps.html.md | 15 ++-- .../intro/getting-started/running.html.md | 4 +- .../source/intro/getting-started/ui.html.md | 4 +- website/source/intro/index.html.markdown | 42 ++++++++-- website/source/intro/use-cases.html.markdown | 79 +++++++++++++------ website/source/intro/vs/index.html.markdown | 33 +++++--- website/source/layouts/intro.erb | 2 +- 7 files changed, 130 insertions(+), 49 deletions(-) diff --git a/website/source/intro/getting-started/next-steps.html.md b/website/source/intro/getting-started/next-steps.html.md index 34a50a6f7..0b9e83cdc 100644 --- a/website/source/intro/getting-started/next-steps.html.md +++ b/website/source/intro/getting-started/next-steps.html.md @@ -15,14 +15,17 @@ to use to improve your environment. We've covered the basics of all the core features of Nomad in this guide. We recommend exploring the following resources as next steps. - * [Documentation](/docs/index.html) - The documentation is an in-depth - reference guide to all the features of Nomad. + * [Guides](/guides/index.html) - The Guides provide best practices and + guidance for using and operating Nomad in a real-world production setting. - * [Creating a Cluster](/guides/cluster/bootstrapping.html) - Additional details on - creating a production worthy Nomad Cluster. + * [Docs](/docs/index.html) - The Docs provide detailed reference information + all available features and options of Nomad. - * [Operating a Job](/guides/operating-a-job/index.html) - Additional details on how to - run a job in production. + * [Job Lifecycle](/guides/operating-a-job/index.html) - Additional details + specific to runnning a job in production. + + * [Creating a Cluster](/guides/operations/cluster/bootstrapping.html) - Additional + details on creating a production worthy Nomad Cluster. * [Example Terraform configuration](https://github.com/hashicorp/nomad/tree/master/terraform) - Use Terraform to automatically provision a cluster in AWS. diff --git a/website/source/intro/getting-started/running.html.md b/website/source/intro/getting-started/running.html.md index 72e4242e5..f4d007eb8 100644 --- a/website/source/intro/getting-started/running.html.md +++ b/website/source/intro/getting-started/running.html.md @@ -110,7 +110,7 @@ Additional metadata can be viewed by providing the `-detailed` flag. You can use `Ctrl-C` (the interrupt signal) to halt the agent. By default, all signals will cause the agent to forcefully shutdown. -The agent [can be configured](/docs/agent/configuration/index.html#leave_on_terminate) to +The agent [can be configured](/docs/configuration/index.html#leave_on_terminate) to gracefully leave on either the interrupt or terminate signals. After interrupting the agent, you should see it leave the cluster @@ -134,7 +134,7 @@ replication continues to be attempted until the node recovers. Nomad will automatically try to reconnect to _failed_ nodes, allowing it to recover from certain network conditions, while _left_ nodes are no longer contacted. -If an agent is operating as a server, [`leave_on_terminate`](/docs/agent/configuration/index.html#leave_on_terminate) should only +If an agent is operating as a server, [`leave_on_terminate`](/docs/configuration/index.html#leave_on_terminate) should only be set if the server will never rejoin the cluster again. The default value of `false` for `leave_on_terminate` and `leave_on_interrupt` work well for most scenarios. If Nomad servers are part of an auto scaling group where new servers are brought up to replace failed servers, using graceful leave avoids causing a potential availability outage affecting the [consensus protocol](/docs/internals/consensus.html). diff --git a/website/source/intro/getting-started/ui.html.md b/website/source/intro/getting-started/ui.html.md index f4a220fe2..1c3224f80 100644 --- a/website/source/intro/getting-started/ui.html.md +++ b/website/source/intro/getting-started/ui.html.md @@ -1,12 +1,12 @@ --- layout: "intro" -page_title: "Nomad Web UI" +page_title: "Web UI" sidebar_current: "getting-started-ui" description: |- Visit the Nomad Web UI to inspect jobs, allocations, and more. --- -# Nomad Web UI +# Web UI At this point we have a fully functioning cluster with a job running in it. We have learned how to inspect a job using `nomad status`, next we'll learn how to inspect diff --git a/website/source/intro/index.html.markdown b/website/source/intro/index.html.markdown index 68f9593ec..e7ba0ba1a 100644 --- a/website/source/intro/index.html.markdown +++ b/website/source/intro/index.html.markdown @@ -13,16 +13,37 @@ place to start with Nomad. We cover what Nomad is, what problems it can solve, how it compares to existing software, and contains a quick start for using Nomad. -If you are already familiar with the basics of Nomad, the -[documentation](/docs/index.html) provides a better reference -guide for all available features as well as internals. +If you are already familiar with the basics of Nomad, the [Guides](/guides/index.html) +and the [reference documentation](/docs/index.html) will provide a more comprehensive +resource. ## What is Nomad? -Nomad is a tool for managing a cluster of machines and running applications +Nomad is a flexible container orchestration tool that enables an organization to +easily deploy and manage any containerized or legacy application using a single, +unified workflow. Nomad can run a diverse workload of Docker, non-containerized, +microservice, and batch applications, and generally offers the following benefits +to developers and operators: + +* **API-driven Automation**: Workload placement, scaling, and upgrades can be + automated, simplifying operations and eliminating the need for homegrown tooling. +* **Self-service Deployments**: Developers are empowered to service application + lifecycles directly, allowing operators to focus on higher value tasks. +* **Workload Reliability**: Application, node, and driver failures are handled + automatically, reducing the need for manual operator intervention +* **Increased Efficiency and Reduced Cost**: Higher application densities allow + operators to reduce fleet sizes and save money. + +Nomad is trusted by enterprises from a range of sectors including financial, +retail, software, and others to run production workloads at scale across private +infrastructure and the public cloud. + +## How it Works + +At its core, Nomad is a tool for managing a cluster of machines and running applications on them. Nomad abstracts away machines and the location of applications, -and instead enables users to declare what they want to run and Nomad handles -where they should run and how to run them. +and instead enables users to declare what they want to run while Nomad handles +where and how to run them. The key features of Nomad are: @@ -57,6 +78,15 @@ The key features of Nomad are: to support demanding workloads. Nomad has been proven to scale to cluster sizes that exceed 10k nodes in real-world production environments. +## How Nomad Compares to Other Tools + +Nomad differentiates from related tools by virtue of its **simplicity**, **flexibility**, +**scalability**, and **high performance**. Nomad's synergy and integration points with +HashiCorp Terrform, Consul, and Vault make it uniquely suited for easy integration into +an organization's existing workflows, minimizing the time-to-market for critical initiatives. +See the [Nomad vs. Other Software](/intro/vs/index.html) page for additional details and +comparisons. + ## Next Steps See the page on [Nomad use cases](/intro/use-cases.html) to see the diff --git a/website/source/intro/use-cases.html.markdown b/website/source/intro/use-cases.html.markdown index f8ac9f48a..bca1d99a8 100644 --- a/website/source/intro/use-cases.html.markdown +++ b/website/source/intro/use-cases.html.markdown @@ -3,35 +3,70 @@ layout: "intro" page_title: "Use Cases" sidebar_current: "use-cases" description: |- - This page lists some concrete use cases for Nomad, but the possible use cases are much broader than what we cover. + This page lists some concrete use cases for Nomad, but the possible use cases + are much broader than what we cover. --- # Use Cases -Before understanding use cases, it's useful to know [what Nomad is](/intro/index.html). -This page lists some concrete use cases for Nomad, but the possible use cases are -much broader than what we cover. +This page lists Nomad's core use cases. Please note that the full range of potential +use cases is much broader than what is currently covered here. Reading through the +[Introduction to Nomad](/intro/index.html) is highly recommended before diving into +the use cases. -## Microservices Platform +## Docker Container Management -Microservices, or Service Oriented Architectures (SOA), are a design paradigm in which many -services with narrow scope, tight state encapsulation, and API driven interfaces interact together -to form a larger application. However, they add an operational challenge of managing hundreds -or thousands of services instead of a few large applications. Nomad provides a platform for -managing microservices, making it easier to adopt the paradigm. +Organizations are increasingly moving towards a Docker centric workflow for +application deployment and management. This transition requires new tooling +to automate placement, perform job updates, enable self-service for developers, +and to handle failures automatically. Nomad supports a [first-class Docker workflow](/docs/drivers/docker.html) +and integrates seamlessly with [Consul](/guides/operations/consul-integration/index.html) +and [Vault](/guides/operations/vault-integration/index.html) to enable a complete solution +while maximizing operational flexibility. Nomad is easy to use, can scale to +thousands of nodes in a single cluster, and can easily deploy across private data +centers and multiple clouds. -## Hybrid Cloud Deployments +## Legacy Application Deployment -Nomad is designed to handle multi-datacenter and multi-region deployments and is cloud agnostic. -This allows Nomad to schedule in private datacenters running bare metal, OpenStack, or VMware -alongside an AWS, Azure, or GCE cloud deployment. This makes it easier to migrate workloads -incrementally, or to utilize the cloud for bursting. +A virtual machine based application deployment strategy can lead to low hardware +utlization rates and high infrastructure costs. While a Docker-based deployment +strategy can be impractical for some organizations or use cases, the potential for +greater automation, increased resilience, and reduced cost is very attractive. +Nomad natively supports running legacy applications, static binaries, JARs, and +simple OS commands directly. Workloads are natively isolated at runtime and bin +packed to maximize efficiency and utilization (reducing cost). Developers and +operators benefit from API-driven automation and enhanced reliability for +applications through automatic failure handling. + +## Microservices + +Microservices and Service Oriented Architectures (SOA) are a design paradigm in +which many services with narrow scope, tight state encapsulation, and API driven +communication interact together to form a larger solution. However, managing hundreds +or thousands of services instead of a few large applications creates an operational +challenge. Nomad elegantly integrates with [Consul](/guides/operations/consul-integration/index.html) +for automatic service registration and dynamic rendering of configuration files. Nomad +and Consul together provide an ideal solution for managing microservices, making it +easier to adopt the paradigm. + +## Batch Processing Workloads + +As data science and analytics teams grow is size and complexity, they increasingly +benefit from highly performant and scalable tools that can run batch workloads with +minimal operational overhead. Nomad can natively run batch jobs, [parameterized](https://www.hashicorp.com/blog/replacing-queues-with-nomad-dispatch) jobs, and [Spark](https://github.com/hashicorp/nomad-spark) +workloads. Nomad's architecture enables easy scalability and an optimistically +concurrent scheduling strategy that can yield [thousands of container deployments per +second](https://www.hashicorp.com/c1m). Alternatives are overly complex and limited +in terms of their scheduling throughput, scalability, and multi-cloud capabilities. + +**Related video**: [End to End Production Nomad at Citadel](https://www.youtube.com/watch?reload=9&v=ZOBcGpGsboA) + +## Multi-region and Multi-cloud Deployments + +Nomad is designed to natively handle multi-datacenter and multi-region deployments +and is cloud agnostic. This allows Nomad to schedule in private datacenters running +bare metal, OpenStack, or VMware alongside an AWS, Azure, or GCE cloud deployment. +This makes it easier to migrate workloads incrementally and to utilize the cloud +for bursting. -## E-Commerce -A typical E-Commerce website has a few types of workloads. There are long-lived services -used for web serving. These include the load balancer, web frontends, API servers, and OLTP databases. -Batch processing using Hadoop or Spark may run periodically for business reporting, user targeting, -or generating product recommendations. Nomad allows all these workloads to share an underlying cluster, -increasing utilization, reducing cost, simplifying scaling and providing a clean abstraction -for developers. diff --git a/website/source/intro/vs/index.html.markdown b/website/source/intro/vs/index.html.markdown index 2dfd894e2..17de4ce26 100644 --- a/website/source/intro/vs/index.html.markdown +++ b/website/source/intro/vs/index.html.markdown @@ -8,16 +8,29 @@ description: |- # Nomad vs. Other Software -Nomad is a cluster manager and scheduler. There are many related categories -including cluster managers, resource managers, workload managers, and schedulers. -There are many existing tools in each category, and the comparisons are not exhaustive -of the entire space. +The following characteristics generally differentiate Nomad from related products: -Due to the bias of the comparisons being on the Nomad website, we attempt -to only use facts. If you find something that is invalid or out of date -in the comparisons, please -[open an issue](https://github.com/hashicorp/nomad/issues) and we'll +* **Simplicity**: Nomad runs as a single process with zero external dependencies. + Operators can easily provision, manage, and scale Nomad. Developers can easily + define and run applications. +* **Flexibility**: Nomad can run a diverse workload of containerized, legacy, + microservice, and batch applications. Nomad can schedule service, batch + processing and system jobs, and can run on both Linux and Windows. +* **Scalability and High Performance**: Nomad can schedule thousands of containers + per second, scale to thousands of nodes in a single cluster, and easily federate + across regions and cloud providers. +* **HashiCorp Synergy**: Nomad elegantly integrates with Vault for secrets + management and Consul for service discovery and dynamic configuration. Nomad's + Consul-like architecture and Terraform-like job specification lower the barrier + to entry for existing users of the HashiCorp stack. + +There are many relevant categories for comparison including cluster managers, +resource managers, workload managers, and schedulers. There are many existing +tools in each category, and the comparisons are not exhaustive of the entire space. + +Due to the bias of the comparisons being on the Nomad website, we attempt to only +use facts. If you find something that is invalid or out of date in the comparisons, +please [open an issue](https://github.com/hashicorp/nomad/issues) and we will address it as soon as possible. -Use the navigation on the left to read comparisons of Nomad versus other -systems. +Use the navigation on the left to read comparisons of Nomad versus other systems. diff --git a/website/source/layouts/intro.erb b/website/source/layouts/intro.erb index 4c97acb16..af90ab8ce 100644 --- a/website/source/layouts/intro.erb +++ b/website/source/layouts/intro.erb @@ -68,7 +68,7 @@ > - Nomad UI + Web UI > From cb0333069cfbef49f2c67adc4ce54ceb0c181ed5 Mon Sep 17 00:00:00 2001 From: Rob Genova Date: Fri, 22 Jun 2018 20:46:35 +0000 Subject: [PATCH 04/16] Fix broken links in docs/commands --- .../source/docs/commands/agent.html.md.erb | 46 +++++++++---------- .../docs/commands/node/config.html.md.erb | 2 +- .../docs/commands/node/drain.html.md.erb | 2 +- .../source/docs/commands/operator.html.md.erb | 4 +- .../operator/autopilot-get-config.html.md.erb | 2 +- .../operator/autopilot-set-config.html.md.erb | 6 +-- .../operator/raft-list-peers.html.md.erb | 2 +- .../operator/raft-remove-peer.html.md.erb | 2 +- 8 files changed, 33 insertions(+), 33 deletions(-) diff --git a/website/source/docs/commands/agent.html.md.erb b/website/source/docs/commands/agent.html.md.erb index faebc7e86..f1aab5e0b 100644 --- a/website/source/docs/commands/agent.html.md.erb +++ b/website/source/docs/commands/agent.html.md.erb @@ -14,7 +14,8 @@ or server functionality, including exposing interfaces for client consumption and running jobs. Due to the power and flexibility of this command, the Nomad agent is documented -in its own section. See the [Nomad Agent](/docs/agent/index.html) section for +in its own section. See the [Nomad Agent](/guides/operations/agent/index.html) +guide and the [Configuration](/docs/configuration/index.html) documentation section for more information on how to use this command and the options it has. ## Command-line Options @@ -24,39 +25,38 @@ via CLI arguments. The `agent` command accepts the following arguments: * `-alloc-dir=`: Equivalent to the Client [alloc_dir](#alloc_dir) config option. -* `-acl-enabled`: Equivalent to the ACL [enabled](/docs/agent/configuration/acl.html#enabled) config option. -* `-acl-replication-token`: Equivalent to the ACL [replication_token](/docs/agent/configuration/acl.html#replication_token) config option. +* `-acl-enabled`: Equivalent to the ACL [enabled](/docs/configuration/acl.html#enabled) config option. +* `-acl-replication-token`: Equivalent to the ACL [replication_token](/docs/configuration/acl.html#replication_token) config option. * `-bind=
`: Equivalent to the [bind_addr](#bind_addr) config option. * `-bootstrap-expect=`: Equivalent to the [bootstrap_expect](#bootstrap_expect) config option. * `-client`: Enable client mode on the local agent. * `-config=`: Specifies the path to a configuration file or a directory of configuration files to load. Can be specified multiple times. -* `-consul-address=`: Equivalent to the [address](/docs/agent/configuration/consul.html#address) config option. -* `-consul-auth=`: Equivalent to the [auth](/docs/agent/configuration/consul.html#auth) config option. -* `-consul-auto-advertise`: Equivalent to the [auto_advertise](/docs/agent/configuration/consul.html#auto_advertise) config option. -* `-consul-ca-file=`: Equivalent to the [ca_file](/docs/agent/configuration/consul.html#ca_file) config option. -* `-consul-cert-file=`: Equivalent to the [cert_file](/docs/agent/configuration/consul.html#cert_file) config option. -* `-consul-checks-use-advertise`: Equivalent to the [checks_use_advertise](/docs/agent/configuration/consul.html#checks_use_advertise) config option. -* `-consul-client-auto-join`: Equivalent to the [client_auto_join](/docs/agent/configuration/consul.html#client_auto_join) config option. -* `-consul-client-service-name=`: Equivalent to the [client_service_name](/docs/agent/configuration/consul.html#client_service_name) config option. -* `-consul-client-http-check-name=`: Equivalent to the [client_http_check_name](/docs/agent/configuration/consul.html#client_http_check_name) config option. -* `-consul-key-file=`: Equivalent to the [key_file](/docs/agent/configuration/consul.html#key_file) config option. -* `-consul-server-service-name=`: Equivalent to the [server_service_name](/docs/agent/configuration/consul.html#server_service_name) config option. -* `-consul-server-http-check-name=`: Equivalent to the [server_http_check_name](/docs/agent/configuration/consul.html#server_http_check_name) config option. -* `-consul-server-serf-check-name=`: Equivalent to the [server_serf_check_name](/docs/agent/configuration/consul.html#server_serf_check_name) config option. -* `-consul-server-rpc-check-name=`: Equivalent to the [server_rpc_check_name](/docs/agent/configuration/consul.html#server_rpc_check_name) config option. -* `-consul-server-auto-join`: Equivalent to the [server_auto_join](/docs/agent/configuration/consul.html#server_auto_join) config option. -* `-consul-ssl`: Equivalent to the [ssl](/docs/agent/configuration/consul.html#ssl) config option. -* `-consul-token=`: Equivalent to the [token](/docs/agent/configuration/consul.html#token) config option. -* `-consul-verify-ssl`: Equivalent to the [verify_ssl](/docs/agent/configuration/consul.html#verify_ssl) config option. +* `-consul-address=`: Equivalent to the [address](/docs/configuration/consul.html#address) config option. +* `-consul-auth=`: Equivalent to the [auth](/docs/configuration/consul.html#auth) config option. +* `-consul-auto-advertise`: Equivalent to the [auto_advertise](/docs/configuration/consul.html#auto_advertise) config option. +* `-consul-ca-file=`: Equivalent to the [ca_file](/docs/configuration/consul.html#ca_file) config option. +* `-consul-cert-file=`: Equivalent to the [cert_file](/docs/configuration/consul.html#cert_file) config option. +* `-consul-checks-use-advertise`: Equivalent to the [checks_use_advertise](/docs/configuration/consul.html#checks_use_advertise) config option. +* `-consul-client-auto-join`: Equivalent to the [client_auto_join](/docs/configuration/consul.html#client_auto_join) config option. +* `-consul-client-service-name=`: Equivalent to the [client_service_name](/docs/configuration/consul.html#client_service_name) config option. +* `-consul-client-http-check-name=`: Equivalent to the [client_http_check_name](/docs/configuration/consul.html#client_http_check_name) config option. +* `-consul-key-file=`: Equivalent to the [key_file](/docs/configuration/consul.html#key_file) config option. +* `-consul-server-service-name=`: Equivalent to the [server_service_name](/docs/configuration/consul.html#server_service_name) config option. +* `-consul-server-http-check-name=`: Equivalent to the [server_http_check_name](/docs/configuration/consul.html#server_http_check_name) config option. +* `-consul-server-serf-check-name=`: Equivalent to the [server_serf_check_name](/docs/configuration/consul.html#server_serf_check_name) config option. +* `-consul-server-rpc-check-name=`: Equivalent to the [server_rpc_check_name](/docs/configuration/consul.html#server_rpc_check_name) config option. +* `-consul-server-auto-join`: Equivalent to the [server_auto_join](/docs/configuration/consul.html#server_auto_join) config option. +* `-consul-ssl`: Equivalent to the [ssl](/docs/configuration/consul.html#ssl) config option. +* `-consul-token=`: Equivalent to the [token](/docs/configuration/consul.html#token) config option. +* `-consul-verify-ssl`: Equivalent to the [verify_ssl](/docs/configuration/consul.html#verify_ssl) config option. * `-data-dir=`: Equivalent to the [data_dir](#data_dir) config option. * `-dc=`: Equivalent to the [datacenter](#datacenter) config option. * `-dev`: Start the agent in development mode. This enables a pre-configured dual-role agent (client + server) which is useful for developing or testing Nomad. No other configuration is required to start the agent in this mode. -* `-encrypt`: Set the Serf encryption key. See [Agent - Encryption](/docs/agent/encryption.html) for more details. +* `-encrypt`: Set the Serf encryption key. See the [Encryption Overview](/guides/security/encryption.html) for more details. * `-join=
`: Address of another agent to join upon starting up. This can be specified multiple times to specify multiple agents to join. * `-log-level=`: Equivalent to the [log_level](#log_level) config option. diff --git a/website/source/docs/commands/node/config.html.md.erb b/website/source/docs/commands/node/config.html.md.erb index aeda023a9..f81b88d55 100644 --- a/website/source/docs/commands/node/config.html.md.erb +++ b/website/source/docs/commands/node/config.html.md.erb @@ -30,7 +30,7 @@ description below for specific usage information and requirements. * `-servers`: List the client's known servers. Client nodes do not participate in the gossip pool, and instead register with these servers periodically over the network. The initial value of this list may come from configuration files - using the [`servers`](/docs/agent/configuration/client.html#servers) + using the [`servers`](/docs/configuration/client.html#servers) configuration option in the client block. * `-update-servers`: Updates the client's server list using the provided diff --git a/website/source/docs/commands/node/drain.html.md.erb b/website/source/docs/commands/node/drain.html.md.erb index 1abbc4cfd..e26fb1b5c 100644 --- a/website/source/docs/commands/node/drain.html.md.erb +++ b/website/source/docs/commands/node/drain.html.md.erb @@ -28,7 +28,7 @@ placed on another node about to be drained. The [node status](/docs/commands/node/status.html) command compliments this nicely by providing the current drain status of a given node. -See the [Decommissioning Nodes guide](/guides/node-draining.html) for detailed +See the [Workload Migration guide](/guides/operations/node-draining.html) for detailed examples of node draining. ## Usage diff --git a/website/source/docs/commands/operator.html.md.erb b/website/source/docs/commands/operator.html.md.erb index c96d14e54..4bad91092 100644 --- a/website/source/docs/commands/operator.html.md.erb +++ b/website/source/docs/commands/operator.html.md.erb @@ -14,9 +14,9 @@ as interacting with the Raft subsystem. This was added in Nomad 0.5.5. ~> Use this command with extreme caution, as improper use could lead to a Nomad outage and even loss of data. -See the [Outage Recovery](/guides/outage.html) guide for some examples of how +See the [Outage Recovery](/guides/operations/outage.html) guide for some examples of how this command is used. For an API to perform these operations programmatically, -please see the documentation for the [Operator](/guides/outage.html) +please see the documentation for the [Operator](/api/operator.html) endpoint. ## Usage diff --git a/website/source/docs/commands/operator/autopilot-get-config.html.md.erb b/website/source/docs/commands/operator/autopilot-get-config.html.md.erb index 37a4435f2..ac4e0734f 100644 --- a/website/source/docs/commands/operator/autopilot-get-config.html.md.erb +++ b/website/source/docs/commands/operator/autopilot-get-config.html.md.erb @@ -9,7 +9,7 @@ description: > # Command: operator autopilot get-config The Autopilot operator command is used to view the current Autopilot configuration. See the -[Autopilot Guide](/guides/autopilot.html) for more information about Autopilot. +[Autopilot Guide](/guides/operations/autopilot.html) for more information about Autopilot. ## Usage diff --git a/website/source/docs/commands/operator/autopilot-set-config.html.md.erb b/website/source/docs/commands/operator/autopilot-set-config.html.md.erb index 4980e9688..d935c7278 100644 --- a/website/source/docs/commands/operator/autopilot-set-config.html.md.erb +++ b/website/source/docs/commands/operator/autopilot-set-config.html.md.erb @@ -9,7 +9,7 @@ description: > # Command: operator autopilot set-config The Autopilot operator command is used to set the current Autopilot configuration. See the -[Autopilot Guide](/guides/autopilot.html) for more information about Autopilot. +[Autopilot Guide](/guides/operations/autopilot.html) for more information about Autopilot. ## Usage @@ -41,11 +41,11 @@ running Raft protocol version 3 or higher. Must be a duration value such as `10s new servers until it can perform a migration. Must be one of `[true|false]`. * `-redundancy-zone-tag`- (Enterprise-only) Controls the - [`redundancy_zone`](/docs/agent/configuration/server.html#redundancy_zone) + [`redundancy_zone`](/docs/configuration/server.html#redundancy_zone) used for separating servers into different redundancy zones. * `-upgrade-version-tag` - (Enterprise-only) Controls the - [`upgrade_version`](/docs/agent/configuration/server.html#upgrade_version) to + [`upgrade_version`](/docs/configuration/server.html#upgrade_version) to use for version info when performing upgrade migrations. If left blank, the Nomad version will be used. diff --git a/website/source/docs/commands/operator/raft-list-peers.html.md.erb b/website/source/docs/commands/operator/raft-list-peers.html.md.erb index 027a87fab..26bef9254 100644 --- a/website/source/docs/commands/operator/raft-list-peers.html.md.erb +++ b/website/source/docs/commands/operator/raft-list-peers.html.md.erb @@ -11,7 +11,7 @@ description: > The Raft list-peers command is used to display the current Raft peer configuration. -See the [Outage Recovery](/guides/outage.html) guide for some examples of how +See the [Outage Recovery](/guides/operations/outage.html) guide for some examples of how this command is used. For an API to perform these operations programmatically, please see the documentation for the [Operator](/api/operator.html) endpoint. diff --git a/website/source/docs/commands/operator/raft-remove-peer.html.md.erb b/website/source/docs/commands/operator/raft-remove-peer.html.md.erb index 0cf66000e..37e6fbaa9 100644 --- a/website/source/docs/commands/operator/raft-remove-peer.html.md.erb +++ b/website/source/docs/commands/operator/raft-remove-peer.html.md.erb @@ -19,7 +19,7 @@ to clean up by simply running [`nomad server force-leave`](/docs/commands/server/force-leave.html) instead of this command. -See the [Outage Recovery](/guides/outage.html) guide for some examples of how +See the [Outage Recovery](/guides/operations/outage.html) guide for some examples of how this command is used. For an API to perform these operations programmatically, please see the documentation for the [Operator](/api/operator.html) endpoint. From 7914abdcee906bd234b655b5f5199f4e7d221b35 Mon Sep 17 00:00:00 2001 From: Rob Genova Date: Fri, 22 Jun 2018 20:47:33 +0000 Subject: [PATCH 05/16] Fix broken links in docs/configuration --- website/source/docs/configuration/acl.html.md | 2 +- .../docs/configuration/autopilot.html.md | 8 +- .../source/docs/configuration/client.html.md | 8 +- .../source/docs/configuration/consul.html.md | 4 +- .../source/docs/configuration/index.html.md | 18 +-- .../docs/configuration/sentinel.html.md | 2 +- .../source/docs/configuration/server.html.md | 18 +-- .../docs/configuration/server_join.html.md | 108 +++++++++++++++++- .../docs/configuration/telemetry.html.md | 4 +- website/source/docs/configuration/tls.html.md | 4 +- .../source/docs/configuration/vault.html.md | 8 +- 11 files changed, 142 insertions(+), 42 deletions(-) diff --git a/website/source/docs/configuration/acl.html.md b/website/source/docs/configuration/acl.html.md index 0cd0a9c45..f430114b6 100644 --- a/website/source/docs/configuration/acl.html.md +++ b/website/source/docs/configuration/acl.html.md @@ -1,7 +1,7 @@ --- layout: "docs" page_title: "acl Stanza - Agent Configuration" -sidebar_current: "docs-agent-configuration-acl" +sidebar_current: "docs-configuration-acl" description: |- The "acl" stanza configures the Nomad agent to enable ACLs and tune various parameters. --- diff --git a/website/source/docs/configuration/autopilot.html.md b/website/source/docs/configuration/autopilot.html.md index 6cf637c9e..9e02537c4 100644 --- a/website/source/docs/configuration/autopilot.html.md +++ b/website/source/docs/configuration/autopilot.html.md @@ -1,7 +1,7 @@ --- layout: "docs" page_title: "autopilot Stanza - Agent Configuration" -sidebar_current: "docs-agent-configuration-autopilot" +sidebar_current: "docs-configuration-autopilot" description: |- The "autopilot" stanza configures the Nomad agent to configure Autopilot behavior. --- @@ -18,7 +18,7 @@ description: |- The `autopilot` stanza configures the Nomad agent to configure Autopilot behavior. -For more information about Autopilot, see the [Autopilot Guide](/guides/autopilot.html). +For more information about Autopilot, see the [Autopilot Guide](/guides/operations/autopilot.html). ```hcl autopilot { @@ -51,7 +51,7 @@ autopilot { - `enable_redundancy_zones` `(bool: false)` - (Enterprise-only) Controls whether Autopilot separates servers into zones for redundancy, in conjunction with the - [redundancy_zone](/docs/agent/configuration/server.html#redundancy_zone) parameter. + [redundancy_zone](/docs/configuration/server.html#redundancy_zone) parameter. Only one server in each zone can be a voting member at one time. - `disable_upgrade_migration` `(bool: false)` - (Enterprise-only) Disables Autopilot's @@ -61,5 +61,5 @@ autopilot { - `enable_custom_upgrades` `(bool: false)` - (Enterprise-only) Specifies whether to enable using custom upgrade versions when performing migrations, in conjunction with - the [upgrade_version](/docs/agent/configuration/server.html#upgrade_version) parameter. + the [upgrade_version](/docs/configuration/server.html#upgrade_version) parameter. diff --git a/website/source/docs/configuration/client.html.md b/website/source/docs/configuration/client.html.md index 2ba20be5b..9f990c649 100644 --- a/website/source/docs/configuration/client.html.md +++ b/website/source/docs/configuration/client.html.md @@ -1,7 +1,7 @@ --- layout: "docs" page_title: "client Stanza - Agent Configuration" -sidebar_current: "docs-agent-configuration-client" +sidebar_current: "docs-configuration-client" description: |- The "client" stanza configures the Nomad agent to accept jobs as assigned by the Nomad server, join the cluster, and specify driver-specific configuration. @@ -32,7 +32,7 @@ client { - `alloc_dir` `(string: "[data_dir]/alloc")` - Specifies the directory to use for allocation data. By default, this is the top-level - [data_dir](/docs/agent/configuration/index.html#data_dir) suffixed with + [data_dir](/docs/configuration/index.html#data_dir) suffixed with "alloc", like `"/opt/nomad/alloc"`. This must be an absolute path - `chroot_env` ([ChrootEnv](#chroot_env-parameters): nil) - @@ -98,7 +98,7 @@ client { - `state_dir` `(string: "[data_dir]/client")` - Specifies the directory to use to store client state. By default, this is - the top-level - [data_dir](/docs/agent/configuration/index.html#data_dir) suffixed with + [data_dir](/docs/configuration/index.html#data_dir) suffixed with "client", like `"/opt/nomad/client"`. This must be an absolute path. - `gc_interval` `(string: "1m")` - Specifies the interval at which Nomad @@ -356,4 +356,4 @@ client { } } ``` -[server-join]: /docs/agent/configuration/server_join.html "Server Join" +[server-join]: /docs/configuration/server_join.html "Server Join" diff --git a/website/source/docs/configuration/consul.html.md b/website/source/docs/configuration/consul.html.md index a0189d96c..2f183652e 100644 --- a/website/source/docs/configuration/consul.html.md +++ b/website/source/docs/configuration/consul.html.md @@ -1,7 +1,7 @@ --- layout: "docs" page_title: "consul Stanza - Agent Configuration" -sidebar_current: "docs-agent-configuration-consul" +sidebar_current: "docs-configuration-consul" description: |- The "consul" stanza configures the Nomad agent's communication with Consul for service discovery and key-value integration. When @@ -168,4 +168,4 @@ consul { ``` [consul]: https://www.consul.io/ "Consul by HashiCorp" -[bootstrap]: /guides/cluster/automatic.html "Automatic Bootstrapping" +[bootstrap]: /guides/operations/cluster/automatic.html "Automatic Bootstrapping" diff --git a/website/source/docs/configuration/index.html.md b/website/source/docs/configuration/index.html.md index 14ed69c8f..c99720d4f 100644 --- a/website/source/docs/configuration/index.html.md +++ b/website/source/docs/configuration/index.html.md @@ -1,12 +1,12 @@ --- layout: "docs" page_title: "Agent Configuration" -sidebar_current: "docs-agent-configuration" +sidebar_current: "docs-configuration" description: |- Learn about the configuration options available for the Nomad agent. --- -# Agent Configuration +# Nomad Configuration Nomad agents have a variety of parameters that can be specified via configuration files or command-line flags. Configuration files are written in @@ -236,10 +236,10 @@ http_api_response_headers { [hcl]: https://github.com/hashicorp/hcl "HashiCorp Configuration Language" [go-sockaddr/template]: https://godoc.org/github.com/hashicorp/go-sockaddr/template -[consul]: /docs/agent/configuration/consul.html "Nomad Agent consul Configuration" -[vault]: /docs/agent/configuration/vault.html "Nomad Agent vault Configuration" -[tls]: /docs/agent/configuration/tls.html "Nomad Agent tls Configuration" -[client]: /docs/agent/configuration/client.html "Nomad Agent client Configuration" -[sentinel]: /docs/agent/configuration/sentinel.html "Nomad Agent sentinel Configuration" -[server]: /docs/agent/configuration/server.html "Nomad Agent server Configuration" -[acl]: /docs/agent/configuration/acl.html "Nomad Agent ACL Configuration" +[consul]: /docs/configuration/consul.html "Nomad Agent consul Configuration" +[vault]: /docs/configuration/vault.html "Nomad Agent vault Configuration" +[tls]: /docs/configuration/tls.html "Nomad Agent tls Configuration" +[client]: /docs/configuration/client.html "Nomad Agent client Configuration" +[sentinel]: /docs/configuration/sentinel.html "Nomad Agent sentinel Configuration" +[server]: /docs/configuration/server.html "Nomad Agent server Configuration" +[acl]: /docs/configuration/acl.html "Nomad Agent ACL Configuration" diff --git a/website/source/docs/configuration/sentinel.html.md b/website/source/docs/configuration/sentinel.html.md index 05769b453..0b71edd1d 100644 --- a/website/source/docs/configuration/sentinel.html.md +++ b/website/source/docs/configuration/sentinel.html.md @@ -1,7 +1,7 @@ --- layout: "docs" page_title: "sentinel Stanza - Agent Configuration" -sidebar_current: "docs-agent-configuration-sentinel" +sidebar_current: "docs-configuration-sentinel" description: |- The "sentinel" stanza configures the Nomad agent for Sentinel policies and tune various parameters. --- diff --git a/website/source/docs/configuration/server.html.md b/website/source/docs/configuration/server.html.md index 1b3466be5..35de23397 100644 --- a/website/source/docs/configuration/server.html.md +++ b/website/source/docs/configuration/server.html.md @@ -1,7 +1,7 @@ --- layout: "docs" page_title: "server Stanza - Agent Configuration" -sidebar_current: "docs-agent-configuration-server" +sidebar_current: "docs-configuration-server" description: |- The "server" stanza configures the Nomad agent to operate in server mode to participate in scheduling decisions, register with service discovery, handle @@ -51,7 +51,7 @@ server { - `data_dir` `(string: "[data_dir]/server")` - Specifies the directory to use - for server-specific data, including the replicated log. By default, this is - - the top-level [data_dir](/docs/agent/configuration/index.html#data_dir) + the top-level [data_dir](/docs/configuration/index.html#data_dir) suffixed with "server", like `"/opt/nomad/server"`. This must be an absolute path. @@ -70,7 +70,7 @@ server { provided once on each agent's initial startup sequence. If it is provided after Nomad has been initialized with an encryption key, then the provided key is ignored and a warning will be displayed. See the - [Nomad encryption documentation][encryption] for more details on this option + [encryption documentation][encryption] for more details on this option and its impact on the cluster. - `node_gc_threshold` `(string: "24h")` - Specifies how long a node must be in a @@ -127,7 +127,7 @@ server { - `redundancy_zone` `(string: "")` - (Enterprise-only) Specifies the redundancy zone that this server will be a part of for Autopilot management. For more - information, see the [Autopilot Guide](/guides/autopilot.html). + information, see the [Autopilot Guide](/guides/operations/autopilot.html). - `rejoin_after_leave` `(bool: false)` - Specifies if Nomad will ignore a previous leave and attempt to rejoin the cluster when starting. By default, @@ -142,7 +142,7 @@ server { - `upgrade_version` `(string: "")` - A custom version of the format X.Y.Z to use in place of the Nomad version when custom upgrades are enabled in Autopilot. - For more information, see the [Autopilot Guide](/guides/autopilot.html). + For more information, see the [Autopilot Guide](/guides/operations/autopilot.html). ### Deprecated Parameters @@ -169,7 +169,7 @@ server { - `start_join` `(array: [])` - Specifies a list of server addresses to join on startup. If Nomad is unable to join with any of the specified addresses, agent startup will fail. See the [server address - format](/docs/agent/configuration/server_join.html#server-address-format) + format](/docs/configuration/server_join.html#server-address-format) section for more information on the format of the string. This field is deprecated in favor of the [server_join stanza][server-join]. @@ -203,7 +203,7 @@ server { The Nomad servers can automatically bootstrap if Consul is configured. For a more detailed explanation, please see the -[automatic Nomad bootstrapping documentation](/guides/cluster/automatic.html). +[automatic Nomad bootstrapping documentation](/guides/operations/cluster/automatic.html). ### Restricting Schedulers @@ -218,5 +218,5 @@ server { } ``` -[encryption]: /docs/agent/encryption.html "Nomad Agent Encryption" -[server-join]: /docs/agent/configuration/server_join.html "Server Join" +[encryption]: /guides/security/encryption.html "Nomad Encryption Overview" +[server-join]: /docs/configuration/server_join.html "Server Join" diff --git a/website/source/docs/configuration/server_join.html.md b/website/source/docs/configuration/server_join.html.md index 82620a781..3869522c0 100644 --- a/website/source/docs/configuration/server_join.html.md +++ b/website/source/docs/configuration/server_join.html.md @@ -1,7 +1,7 @@ --- layout: "docs" page_title: "server_join Stanza - Agent Configuration" -sidebar_current: "docs-agent-configuration--server-join" +sidebar_current: "docs-configuration--server-join" description: |- The "server_join" stanza specifies how the Nomad agent will discover and connect to Nomad servers. --- @@ -43,8 +43,8 @@ server_join { Address format includes both using IP addresses as well as an interface to the [go-discover](https://github.com/hashicorp/go-discover) library for doing - automated cluster joining using cloud metadata. See [Cloud - Auto-join][cloud_auto_join] for more information. + automated cluster joining using cloud metadata. See the [Cloud Auto-join](#cloud-auto-join) + section below for more information. ``` server_join { @@ -128,4 +128,104 @@ Auto-join][cloud_auto_join] for more information. "provider=aws tag_key=..." => 1.2.3.4:4648 ``` -[cloud_auto_join]: /docs/agent/cloud_auto_join.html "Nomad Cloud Auto-join" +## Cloud Auto-join + +The following sections describe the Cloud Auto-join `retry_join` options that are specific +to a subset of supported cloud providers. For information on all providers, see further +documentation in [go-discover](https://github.com/hashicorp/go-discover). + +### Amazon EC2 + +This returns the first private IP address of all servers in the given +region which have the given `tag_key` and `tag_value`. + + +```json +{ + "retry_join": ["provider=aws tag_key=... tag_value=..."] +} +``` + +- `provider` (required) - the name of the provider ("aws" in this case). +- `tag_key` (required) - the key of the tag to auto-join on. +- `tag_value` (required) - the value of the tag to auto-join on. +- `region` (optional) - the AWS region to authenticate in. +- `addr_type` (optional) - the type of address to discover: `private_v4`, `public_v4`, `public_v6`. Default is `private_v4`. (>= 1.0) +- `access_key_id` (optional) - the AWS access key for authentication (see below for more information about authenticating). +- `secret_access_key` (optional) - the AWS secret access key for authentication (see below for more information about authenticating). + +#### Authentication & Precedence + +- Static credentials `access_key_id=... secret_access_key=...` +- Environment variables (`AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY`) +- Shared credentials file (`~/.aws/credentials` or the path specified by `AWS_SHARED_CREDENTIALS_FILE`) +- ECS task role metadata (container-specific). +- EC2 instance role metadata. + + The only required IAM permission is `ec2:DescribeInstances`, and it is + recommended that you make a dedicated key used only for auto-joining. If the + region is omitted it will be discovered through the local instance's [EC2 + metadata + endpoint](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instance-identity-documents.html). + +### Microsoft Azure + + This returns the first private IP address of all servers in the given region + which have the given `tag_key` and `tag_value` in the tenant and subscription, or in + the given `resource_group` of a `vm_scale_set` for Virtual Machine Scale Sets. + + + ```json +{ + "retry_join": ["provider=azure tag_name=... tag_value=... tenant_id=... client_id=... subscription_id=... secret_access_key=..."] +} +``` + +- `provider` (required) - the name of the provider ("azure" in this case). +- `tenant_id` (required) - the tenant to join machines in. +- `client_id` (required) - the client to authenticate with. +- `secret_access_key` (required) - the secret client key. + +Use these configuration parameters when using tags: +- `tag_name` - the name of the tag to auto-join on. +- `tag_value` - the value of the tag to auto-join on. + +Use these configuration parameters when using Virtual Machine Scale Sets (Consul 1.0.3 and later): +- `resource_group` - the name of the resource group to filter on. +- `vm_scale_set` - the name of the virtual machine scale set to filter on. + + When using tags the only permission needed is the `ListAll` method for `NetworkInterfaces`. When using + Virtual Machine Scale Sets the only role action needed is `Microsoft.Compute/virtualMachineScaleSets/*/read`. + +### Google Compute Engine + +This returns the first private IP address of all servers in the given +project which have the given `tag_value`. +``` + +```json +{ +"retry_join": ["provider=gce project_name=... tag_value=..."] +} +``` + +- `provider` (required) - the name of the provider ("gce" in this case). +- `tag_value` (required) - the value of the tag to auto-join on. +- `project_name` (optional) - the name of the project to auto-join on. Discovered if not set. +- `zone_pattern` (optional) - the list of zones can be restricted through an RE2 compatible regular expression. If omitted, servers in all zones are returned. +- `credentials_file` (optional) - the credentials file for authentication. See below for more information. + +#### Authentication & Precedence + +- Use credentials from `credentials_file`, if provided. +- Use JSON file from `GOOGLE_APPLICATION_CREDENTIALS` environment variable. +- Use JSON file in a location known to the gcloud command-line tool. +- On Windows, this is `%APPDATA%/gcloud/application_default_credentials.json`. +- On other systems, `$HOME/.config/gcloud/application_default_credentials.json`. +- On Google Compute Engine, use credentials from the metadata +server. In this final case any provided scopes are ignored. + +Discovery requires a [GCE Service +Account](https://cloud.google.com/compute/docs/access/service-accounts). +Credentials are searched using the following paths, in order of precedence. + diff --git a/website/source/docs/configuration/telemetry.html.md b/website/source/docs/configuration/telemetry.html.md index bf5b486e3..861b4a8dc 100644 --- a/website/source/docs/configuration/telemetry.html.md +++ b/website/source/docs/configuration/telemetry.html.md @@ -1,7 +1,7 @@ --- layout: "docs" page_title: "telemetry Stanza - Agent Configuration" -sidebar_current: "docs-agent-configuration-telemetry" +sidebar_current: "docs-configuration-telemetry" description: |- The "telemetry" stanza configures Nomad's publication of metrics and telemetry to third-party systems. @@ -31,7 +31,7 @@ telemetry { This section of the documentation only covers the configuration options for `telemetry` stanza. To understand the architecture and metrics themselves, -please see the [Nomad telemetry documentation](/docs/agent/telemetry.html). +please see the [Telemetry guide](/guides/operations/monitoring/telemetry.html). ## `telemetry` Parameters diff --git a/website/source/docs/configuration/tls.html.md b/website/source/docs/configuration/tls.html.md index b79a1ac7e..cc2367c4f 100644 --- a/website/source/docs/configuration/tls.html.md +++ b/website/source/docs/configuration/tls.html.md @@ -1,7 +1,7 @@ --- layout: "docs" page_title: "tls Stanza - Agent Configuration" -sidebar_current: "docs-agent-configuration-tls" +sidebar_current: "docs-configuration-tls" description: |- The "tls" stanza configures Nomad's TLS communication via HTTP and RPC to enforce secure cluster communication between servers, clients, and between. @@ -33,7 +33,7 @@ start the Nomad agent. This section of the documentation only covers the configuration options for `tls` stanza. To understand how to setup the certificates themselves, please see -the [Agent's Gossip and RPC Encryption](/docs/agent/encryption.html). +the [Encryption Overview Guide](/guides/security/encryption.html). ## `tls` Parameters diff --git a/website/source/docs/configuration/vault.html.md b/website/source/docs/configuration/vault.html.md index 01207900d..87e30a583 100644 --- a/website/source/docs/configuration/vault.html.md +++ b/website/source/docs/configuration/vault.html.md @@ -1,7 +1,7 @@ --- layout: "docs" page_title: "vault Stanza - Agent Configuration" -sidebar_current: "docs-agent-configuration-vault" +sidebar_current: "docs-configuration-vault" description: |- The "vault" stanza configures Nomad's integration with HashiCorp's Vault. When configured, Nomad can create and distribute Vault tokens to tasks @@ -86,8 +86,8 @@ vault { - `token` `(string: "")` - Specifies the parent Vault token to use to derive child tokens for jobs requesting tokens. - Visit the [Vault Integration](/docs/vault-integration/index.html) - documentation to see how to generate an appropriate token in Vault. + Visit the [Vault Integration Guide](/guides/operations/vault-integration/index.html) + to see how to generate an appropriate token in Vault. !> It is **strongly discouraged** to place the token as a configuration parameter like this, since the token could be checked into source control @@ -150,4 +150,4 @@ token needs to be given to the servers without having to restart them. A reload can be accomplished by sending the process a `SIGHUP` signal. [vault]: https://www.vaultproject.io/ "Vault by HashiCorp" -[nomad-vault]: /docs/vault-integration/index.html "Nomad Vault Integration" +[nomad-vault]: /guides/operations/vault-integration/index.html "Nomad Vault Integration" From 1f77b2b7bb8d6c04e4c7baa38c7d3fba52d38780 Mon Sep 17 00:00:00 2001 From: Rob Genova Date: Fri, 22 Jun 2018 20:48:21 +0000 Subject: [PATCH 06/16] Fix broken links in docs/drivers --- website/source/docs/drivers/docker.html.md | 2 +- website/source/docs/drivers/exec.html.md | 2 +- website/source/docs/drivers/lxc.html.md | 2 +- website/source/docs/drivers/qemu.html.md | 4 ++-- website/source/docs/drivers/raw_exec.html.md | 2 +- website/source/docs/drivers/rkt.html.md | 2 +- 6 files changed, 7 insertions(+), 7 deletions(-) diff --git a/website/source/docs/drivers/docker.html.md b/website/source/docs/drivers/docker.html.md index e907a7423..0bc12f5ec 100644 --- a/website/source/docs/drivers/docker.html.md +++ b/website/source/docs/drivers/docker.html.md @@ -583,7 +583,7 @@ of the Linux Kernel and Docker daemon. ## Client Configuration The `docker` driver has the following [client configuration -options](/docs/agent/configuration/client.html#options): +options](/docs/configuration/client.html#options): * `docker.endpoint` - If using a non-standard socket, HTTP or another location, or if TLS is being used, `docker.endpoint` must be set. If unset, Nomad will diff --git a/website/source/docs/drivers/exec.html.md b/website/source/docs/drivers/exec.html.md index 4f6380b95..2afd7092d 100644 --- a/website/source/docs/drivers/exec.html.md +++ b/website/source/docs/drivers/exec.html.md @@ -131,4 +131,4 @@ the client manages garbage collection locally which mitigates any issue this may create. This list is configurable through the agent client -[configuration file](/docs/agent/configuration/client.html#chroot_env). +[configuration file](/docs/configuration/client.html#chroot_env). diff --git a/website/source/docs/drivers/lxc.html.md b/website/source/docs/drivers/lxc.html.md index 5721cde69..4ab17d7f8 100644 --- a/website/source/docs/drivers/lxc.html.md +++ b/website/source/docs/drivers/lxc.html.md @@ -109,7 +109,7 @@ The `lxc` driver requires the following: ## Client Configuration * `lxc.enable` - The `lxc` driver may be disabled on hosts by setting this - [client configuration][/docs/agent/configuration/client.html##options-parameters] + [client configuration][/docs/configuration/client.html##options-parameters] option to `false` (defaults to `true`). ## Client Attributes diff --git a/website/source/docs/drivers/qemu.html.md b/website/source/docs/drivers/qemu.html.md index 352b80129..4971c59dd 100644 --- a/website/source/docs/drivers/qemu.html.md +++ b/website/source/docs/drivers/qemu.html.md @@ -58,9 +58,9 @@ The `qemu` driver supports the following configuration in the job spec: the monitor socket path is limited to 108 characters. Graceful shutdown will be disabled if qemu is < 2.10.1 and the generated monitor path exceeds this length. You may encounter this issue if you set long - [data_dir](https://www.nomadproject.io/docs/agent/configuration/index.html#data_dir) + [data_dir](/docs/configuration/index.html#data_dir) or - [alloc_dir](https://www.nomadproject.io/docs/agent/configuration/client.html#alloc_dir) + [alloc_dir](/docs/configuration/client.html#alloc_dir) paths.) This feature is currently not supported on Windows. * `port_map` - (Optional) A key-value map of port labels. diff --git a/website/source/docs/drivers/raw_exec.html.md b/website/source/docs/drivers/raw_exec.html.md index 1d01bd90b..3067e3fd3 100644 --- a/website/source/docs/drivers/raw_exec.html.md +++ b/website/source/docs/drivers/raw_exec.html.md @@ -79,7 +79,7 @@ task "example" { The `raw_exec` driver can run on all supported operating systems. For security reasons, it is disabled by default. To enable raw exec, the Nomad client configuration must explicitly enable the `raw_exec` driver in the client's -[options](/docs/agent/configuration/client.html#options): +[options](/docs/configuration/client.html#options): ``` client { diff --git a/website/source/docs/drivers/rkt.html.md b/website/source/docs/drivers/rkt.html.md index b369efb12..f3b17ce9f 100644 --- a/website/source/docs/drivers/rkt.html.md +++ b/website/source/docs/drivers/rkt.html.md @@ -167,7 +167,7 @@ over HTTP. ## Client Configuration The `rkt` driver has the following [client configuration -options](/docs/agent/configuration/client.html#options): +options](/docs/configuration/client.html#options): * `rkt.volumes.enabled`: Defaults to `true`. Allows tasks to bind host paths (`volumes`) inside their container. Binding relative paths is always allowed From 090b7366928d2a58b9cf65ed95818166e7ebe9c7 Mon Sep 17 00:00:00 2001 From: Rob Genova Date: Fri, 22 Jun 2018 20:49:10 +0000 Subject: [PATCH 07/16] Link Enterprise in header and footer to Nomad Enterprise docs page instead of marketing page; add "request more info" links --- .../source/docs/enterprise/autopilot/index.html.md | 7 +++++-- website/source/docs/enterprise/index.html.md | 7 +++++-- .../docs/enterprise/namespaces/index.html.md | 14 ++++++++------ .../source/docs/enterprise/quotas/index.html.md | 10 ++++++---- .../source/docs/enterprise/sentinel/index.html.md | 9 ++++++--- website/source/layouts/layout.erb | 4 ++-- 6 files changed, 32 insertions(+), 19 deletions(-) diff --git a/website/source/docs/enterprise/autopilot/index.html.md b/website/source/docs/enterprise/autopilot/index.html.md index f8806662e..a4a061538 100644 --- a/website/source/docs/enterprise/autopilot/index.html.md +++ b/website/source/docs/enterprise/autopilot/index.html.md @@ -10,7 +10,7 @@ description: |- # Nomad Enterprise Advanced Autopilot -Nomad Enterprise supports Advanced Autopilot capabilities which enable fully +[Nomad Enterprise](https://www.hashicorp.com/go/nomad-enterprise) supports Advanced Autopilot capabilities which enable fully automated server upgrades, higher throughput for reads and scheduling, and hot server failover on a per availability zone basis. See the sections below for additional details on each of these capabilities. @@ -38,5 +38,8 @@ completely lost, only one voter will be lost, so the cluster remains available. If a voter is lost in an availability zone, Autopilot will promote the non-voter to voter automatically, putting the hot standby server into service quickly. -See the [Nomad Autopilot Guide](/guides/autopilot.html) +See the [Nomad Autopilot Guide](/guides/operations/autopilot.html) for a comprehensive overview of Nomad's open source and enterprise Autopilot features. + +Click [here](https://www.hashicorp.com/go/nomad-enterprise) to set up a demo or +request a trial of Nomad Enterprise. diff --git a/website/source/docs/enterprise/index.html.md b/website/source/docs/enterprise/index.html.md index a32ccdcad..f23171b22 100644 --- a/website/source/docs/enterprise/index.html.md +++ b/website/source/docs/enterprise/index.html.md @@ -9,7 +9,7 @@ description: |- # Nomad Enterprise -[Nomad Enterprise](https://www.hashicorp.com/products/nomad/) adds collaboration, +[Nomad Enterprise](https://www.hashicorp.com/go/nomad-enterprise) adds collaboration, operational, and governance capabilities to Nomad. Namespaces allow multiple teams to safely use a shared multi-region deployment. With Resource Quotas, operators can limit resource consumption across teams or projects. Sentinel @@ -23,4 +23,7 @@ links below for a detailed overview of each feature. - [Sentinel Policies](/docs/enterprise/sentinel/index.html) - [Advanced Autopilot](/docs/enterprise/autopilot/index.html) -These features are part of [Nomad Enterprise](https://www.hashicorp.com/products/nomad/). +Click [here](https://www.hashicorp.com/go/nomad-enterprise) to set up a demo or request a trial +of Nomad Enterprise. + + diff --git a/website/source/docs/enterprise/namespaces/index.html.md b/website/source/docs/enterprise/namespaces/index.html.md index 655806c80..a67d18229 100644 --- a/website/source/docs/enterprise/namespaces/index.html.md +++ b/website/source/docs/enterprise/namespaces/index.html.md @@ -10,15 +10,17 @@ description: |- # Nomad Enterprise Namespaces -In [Nomad Enterprise](https://www.hashicorp.com/products/nomad/), a shared -cluster can be partitioned into [namespaces](/guides/namespaces.html) which allows +In [Nomad Enterprise](https://www.hashicorp.com/go/nomad-enterprise), a shared +cluster can be partitioned into [namespaces](/guides/security/namespaces.html) which allows jobs and their associated objects to be isolated from each other and other users of the cluster. Namespaces enhance the usability of a shared cluster by isolating teams from the jobs of others, provide fine grain access control to jobs when coupled with -[ACLs](/guides/acl.html), and can prevent bad actors from negatively impacting -the whole cluster when used in conjunction with -[resource quotas](/docs/enterprise/quotas/index.html). +[ACLs](/guides/security/acl.html), and can prevent bad actors from negatively impacting +the whole cluster when used in conjunction with +[resource quotas](/guides/security/quotas.html). See the +[Namespaces Guide](/guides/security/namespaces.html) for a thorough overview. -See the [Namespaces Guide](/guides/namespaces.html) for a thorough overview. +Click [here](https://www.hashicorp.com/go/nomad-enterprise) to set up a demo or +request a trial of Nomad Enterprise. diff --git a/website/source/docs/enterprise/quotas/index.html.md b/website/source/docs/enterprise/quotas/index.html.md index 1e8f54c17..a280c0da1 100644 --- a/website/source/docs/enterprise/quotas/index.html.md +++ b/website/source/docs/enterprise/quotas/index.html.md @@ -10,12 +10,14 @@ description: |- # Nomad Enterprise Resource Quotas -In [Nomad Enterprise](https://www.hashicorp.com/products/nomad/), operators can -define [quota specifications](/guides/quotas.html) and apply them to namespaces. +In [Nomad Enterprise](https://www.hashicorp.com/go/nomad-enterprise), operators can +define [quota specifications](/guides/security/quotas.html) and apply them to namespaces. When a quota is attached to a namespace, the jobs within the namespace may not consume more resources than the quota specification allows. This allows operators to partition a shared cluster and ensure that no single -actor can consume the whole resources of the cluster. +actor can consume the whole resources of the cluster. See the +[Resource Quotas Guide](/guides/security/quotas.html) for more details. -See the [Resource Quotas Guide](/guides/quotas.html) for more details. +Click [here](https://www.hashicorp.com/go/nomad-enterprise) to set up a demo or +request a trial of Nomad Enterprise. diff --git a/website/source/docs/enterprise/sentinel/index.html.md b/website/source/docs/enterprise/sentinel/index.html.md index 2206acb0c..7c23b0ec1 100644 --- a/website/source/docs/enterprise/sentinel/index.html.md +++ b/website/source/docs/enterprise/sentinel/index.html.md @@ -8,8 +8,8 @@ description: |- # Nomad Enterprise Sentinel Policy Enforcement -In [Nomad Enterprise](https://www.hashicorp.com/products/nomad/), operators can -create [Sentinel policies](/guides/sentinel-policy.html) for fine-grained policy +In [Nomad Enterprise](https://www.hashicorp.com/go/nomad-enterprise), operators can +create [Sentinel policies](/guides/security/sentinel-policy.html) for fine-grained policy enforcement. Sentinel policies build on top of the ACL system and allow operators to define policies such as disallowing jobs to be submitted to production on Fridays. These extremely rich policies are defined as code. For example, to @@ -30,4 +30,7 @@ all_drivers_docker = rule { } ``` -See the [Sentinel Policies Guide](/guides/sentinel-policy.html) for additional details and examples. +See the [Sentinel Policies Guide](/guides/security/sentinel-policy.html) for additional details and examples. + +Click [here](https://www.hashicorp.com/go/nomad-enterprise) to set up a demo or +request a trial of Nomad Enterprise. \ No newline at end of file diff --git a/website/source/layouts/layout.erb b/website/source/layouts/layout.erb index 8d99aa00f..86854bc1f 100644 --- a/website/source/layouts/layout.erb +++ b/website/source/layouts/layout.erb @@ -80,7 +80,7 @@
  • Docs
  • API
  • Resources
    • -
  • Enterprise
    • +
  • Enterprise
  • UI Demo
  • @@ -114,7 +114,7 @@
  • Docs
  • API
  • Resources
    • -
  • Enterprise
    • +
  • Enterprise
  • UI Demo
  • Privacy
  • Security
    • From 5dde6d0e403032ab5958ac1a1ff5be8087f3384a Mon Sep 17 00:00:00 2001 From: Rob Genova Date: Fri, 22 Jun 2018 20:50:42 +0000 Subject: [PATCH 08/16] Fix broken links in docs/job-specification --- website/source/docs/job-specification/constraint.html.md | 2 +- website/source/docs/job-specification/job.html.md | 2 +- website/source/docs/job-specification/migrate.html.md | 2 +- .../source/docs/job-specification/parameterized.html.md | 2 +- website/source/docs/job-specification/service.html.md | 2 +- website/source/docs/job-specification/task.html.md | 8 ++++---- website/source/docs/job-specification/template.html.md | 2 +- 7 files changed, 10 insertions(+), 10 deletions(-) diff --git a/website/source/docs/job-specification/constraint.html.md b/website/source/docs/job-specification/constraint.html.md index 423164586..6f355799d 100644 --- a/website/source/docs/job-specification/constraint.html.md +++ b/website/source/docs/job-specification/constraint.html.md @@ -275,7 +275,7 @@ constraint { [job]: /docs/job-specification/job.html "Nomad job Job Specification" [group]: /docs/job-specification/group.html "Nomad group Job Specification" -[client-meta]: /docs/agent/configuration/client.html#meta "Nomad meta Job Specification" +[client-meta]: /docs/configuration/client.html#meta "Nomad meta Job Specification" [task]: /docs/job-specification/task.html "Nomad task Job Specification" [interpolation]: /docs/runtime/interpolation.html "Nomad interpolation" [node-variables]: /docs/runtime/interpolation.html#node-variables- "Nomad interpolation-Node variables" diff --git a/website/source/docs/job-specification/job.html.md b/website/source/docs/job-specification/job.html.md index e67994572..bbaa03dd7 100644 --- a/website/source/docs/job-specification/job.html.md +++ b/website/source/docs/job-specification/job.html.md @@ -223,4 +223,4 @@ $ VAULT_TOKEN="..." nomad job run example.nomad [task]: /docs/job-specification/task.html "Nomad task Job Specification" [update]: /docs/job-specification/update.html "Nomad update Job Specification" [vault]: /docs/job-specification/vault.html "Nomad vault Job Specification" -[scheduler]: /docs/runtime/schedulers.html "Nomad Scheduler Types" +[scheduler]: /docs/schedulers.html "Nomad Scheduler Types" diff --git a/website/source/docs/job-specification/migrate.html.md b/website/source/docs/job-specification/migrate.html.md index 2ce898ccb..4c8f1dfca 100644 --- a/website/source/docs/job-specification/migrate.html.md +++ b/website/source/docs/job-specification/migrate.html.md @@ -48,7 +48,7 @@ stanza for allocations on that node. The `migrate` stanza is for job authors to define how their services should be migrated, while the node drain deadline is for system operators to put hard limits on how long a drain may take. -See the [Decommissioning Nodes guide](/guides/node-draining.html) for details +See the [Workload Migration Guide](/guides/operations/node-draining.html) for details on node draining. ## `migrate` Parameters diff --git a/website/source/docs/job-specification/parameterized.html.md b/website/source/docs/job-specification/parameterized.html.md index 1679e2c69..9526bddaa 100644 --- a/website/source/docs/job-specification/parameterized.html.md +++ b/website/source/docs/job-specification/parameterized.html.md @@ -157,7 +157,7 @@ job "email-blast" { ``` [batch-type]: /docs/job-specification/job.html#type "Batch scheduler type" -[dispatch command]: /docs/commands/job-dispatch.html "Nomad Job Dispatch Command" +[dispatch command]: /docs/commands/job/dispatch.html "Nomad Job Dispatch Command" [resources]: /docs/job-specification/resources.html "Nomad resources Job Specification" [interpolation]: /docs/runtime/interpolation.html "Nomad Runtime Interpolation" [dispatch_payload]: /docs/job-specification/dispatch_payload.html "Nomad dispatch_payload Job Specification" diff --git a/website/source/docs/job-specification/service.html.md b/website/source/docs/job-specification/service.html.md index 6746b3f4e..7d458ea06 100644 --- a/website/source/docs/job-specification/service.html.md +++ b/website/source/docs/job-specification/service.html.md @@ -622,7 +622,7 @@ system of a task for that driver. [check_restart_stanza]: /docs/job-specification/check_restart.html "check_restart stanza" [consul_grpc]: https://www.consul.io/api/agent/check.html#grpc -[service-discovery]: /docs/service-discovery/index.html "Nomad Service Discovery" +[service-discovery]: /guides/operations/consul-integration/index.html#service-discovery/index.html "Nomad Service Discovery" [interpolation]: /docs/runtime/interpolation.html "Nomad Runtime Interpolation" [network]: /docs/job-specification/network.html "Nomad network Job Specification" [qemu]: /docs/drivers/qemu.html "Nomad qemu Driver" diff --git a/website/source/docs/job-specification/task.html.md b/website/source/docs/job-specification/task.html.md index e2d1cf0ef..76bfb428f 100644 --- a/website/source/docs/job-specification/task.html.md +++ b/website/source/docs/job-specification/task.html.md @@ -195,12 +195,12 @@ task "server" { [meta]: /docs/job-specification/meta.html "Nomad meta Job Specification" [resources]: /docs/job-specification/resources.html "Nomad resources Job Specification" [logs]: /docs/job-specification/logs.html "Nomad logs Job Specification" -[service]: /docs/service-discovery/index.html "Nomad Service Discovery" +[service]: /guides/operations/consul-integration/index.html#service-discovery/index.html "Nomad Service Discovery" [exec]: /docs/drivers/exec.html "Nomad exec Driver" [java]: /docs/drivers/java.html "Nomad Java Driver" [Docker]: /docs/drivers/docker.html "Nomad Docker Driver" [rkt]: /docs/drivers/rkt.html "Nomad rkt Driver" [template]: /docs/job-specification/template.html "Nomad template Job Specification" -[user_drivers]: /docs/agent/configuration/client.html#_quot_user_checked_drivers_quot_ -[user_blacklist]: /docs/agent/configuration/client.html#_quot_user_blacklist_quot_ -[max_kill]: /docs/agent/configuration/client.html#max_kill_timeout +[user_drivers]: /docs/configuration/client.html#_quot_user_checked_drivers_quot_ +[user_blacklist]: /docs/configuration/client.html#_quot_user_blacklist_quot_ +[max_kill]: /docs/configuration/client.html#max_kill_timeout diff --git a/website/source/docs/job-specification/template.html.md b/website/source/docs/job-specification/template.html.md index 3b25f8777..450ffd97a 100644 --- a/website/source/docs/job-specification/template.html.md +++ b/website/source/docs/job-specification/template.html.md @@ -278,7 +278,7 @@ rather than `secret/...`. ## Client Configuration The `template` block has the following [client configuration -options](/docs/agent/configuration/client.html#options): +options](/docs/configuration/client.html#options): * `template.allow_host_source` - Allows templates to specify their source template as an absolute path referencing host directories. Defaults to `true`. From 4f7fb30ee70d55a79d3e19b2b955260b4e83d54f Mon Sep 17 00:00:00 2001 From: Rob Genova Date: Fri, 22 Jun 2018 20:51:41 +0000 Subject: [PATCH 09/16] Misc. changes and fixes to docs/ --- website/source/docs/faq.html.md | 6 +- .../source/docs/runtime/_envvars.html.md.erb | 2 +- .../docs/runtime/environment.html.md.erb | 2 +- .../docs/runtime/interpolation.html.md.erb | 4 +- website/source/docs/schedulers.html.md | 6 +- website/source/layouts/docs.erb | 334 ++++++++---------- 6 files changed, 156 insertions(+), 198 deletions(-) diff --git a/website/source/docs/faq.html.md b/website/source/docs/faq.html.md index 69be72513..6abe65132 100644 --- a/website/source/docs/faq.html.md +++ b/website/source/docs/faq.html.md @@ -16,8 +16,8 @@ Only anonymous information, which cannot be used to identify the user or host, i sent to Checkpoint. An anonymous ID is sent which helps de-duplicate warning messages. This anonymous ID can be disabled. Using the Checkpoint service is optional and can be disabled. -See [`disable_anonymous_signature`](/docs/agent/configuration/index.html#disable_anonymous_signature) -and [`disable_update_check`](/docs/agent/configuration/index.html#disable_update_check). +See [`disable_anonymous_signature`](/docs/configuration/index.html#disable_anonymous_signature) +and [`disable_update_check`](/docs/configuration/index.html#disable_update_check). ## Q: Is Nomad eventually or strongly consistent? @@ -40,4 +40,4 @@ clusters][consul_fed]. [consul_dc]: https://www.consul.io/docs/agent/options.html#_datacenter [consul_fed]: https://www.consul.io/docs/guides/datacenters.html -[nomad_region]: /docs/agent/configuration/index.html#datacenter +[nomad_region]: /docs/configuration/index.html#datacenter diff --git a/website/source/docs/runtime/_envvars.html.md.erb b/website/source/docs/runtime/_envvars.html.md.erb index cdfa6ed76..f504b3f84 100644 --- a/website/source/docs/runtime/_envvars.html.md.erb +++ b/website/source/docs/runtime/_envvars.html.md.erb @@ -73,7 +73,7 @@ VAULT_TOKEN - The task's Vault token. See [Vault Integration](/docs/vault-integration/index.html) for more details + The task's Vault token. See [Vault Integration](/guides/operations/vault-integration/index.html) for more details Network-related Variables diff --git a/website/source/docs/runtime/environment.html.md.erb b/website/source/docs/runtime/environment.html.md.erb index f92f27ba0..fa7c94ce2 100644 --- a/website/source/docs/runtime/environment.html.md.erb +++ b/website/source/docs/runtime/environment.html.md.erb @@ -98,4 +98,4 @@ multiple keys with the same uppercased representation will lead to undefined behavior. [jobspec]: /docs/job-specification/index.html "Nomad Job Specification" -[vault]: /docs/vault-integration/index.html "Nomad Vault Integration" +[vault]: /guides/operations/vault-integration/index.html "Nomad Vault Integration" diff --git a/website/source/docs/runtime/interpolation.html.md.erb b/website/source/docs/runtime/interpolation.html.md.erb index b414e9158..1fbe0ee86 100644 --- a/website/source/docs/runtime/interpolation.html.md.erb +++ b/website/source/docs/runtime/interpolation.html.md.erb @@ -1,12 +1,12 @@ --- layout: "docs" -page_title: "Interpolation - Runtime" +page_title: "Variable Interpolation" sidebar_current: "docs-runtime-interpolation" description: |- Learn about the Nomad's interpolation and interpreted variables. --- -# Interpolation +# Variable Interpolation Nomad supports interpreting two classes of variables, node attributes and runtime environment variables. Node attributes are interpretable in constraints, diff --git a/website/source/docs/schedulers.html.md b/website/source/docs/schedulers.html.md index 70a607be7..9e7a5595d 100644 --- a/website/source/docs/schedulers.html.md +++ b/website/source/docs/schedulers.html.md @@ -1,12 +1,12 @@ --- layout: "docs" -page_title: "Scheduler Types - Runtime" -sidebar_current: "docs-runtime-schedulers" +page_title: "Schedulers" +sidebar_current: "docs-schedulers" description: |- Learn about Nomad's various schedulers. --- -# Scheduler Types +# Schedulers Nomad has three scheduler types that can be used when creating your job: `service`, `batch` and `system`. Here we will describe the differences between diff --git a/website/source/layouts/docs.erb b/website/source/layouts/docs.erb index eea874b8f..6a00e792a 100644 --- a/website/source/layouts/docs.erb +++ b/website/source/layouts/docs.erb @@ -1,139 +1,60 @@ <% wrap_layout :inner do %> <% content_for :sidebar do %> - > - Nomad Agent - - - -
    - > - Internals + > + Job Specification - > - Upgrading + > + Task Drivers - > - FAQ + > + Schedulers + + + > + Runtime Environment + + + > + Variable Interpolation
    @@ -503,6 +457,10 @@ + > + FAQ + + <% end %> From 0bd33ee163fef4f6f31872fe5023305645735081 Mon Sep 17 00:00:00 2001 From: Rob Genova Date: Fri, 22 Jun 2018 20:53:16 +0000 Subject: [PATCH 10/16] Updates to guides/operations --- .../guides/operations/agent/index.html.md | 4 +- .../guides/operations/autopilot.html.md | 14 +- .../operations/cluster/automatic.html.md | 8 +- .../operations/cluster/bootstrapping.html.md | 16 ++- .../cluster/cloud_auto_join.html.md | 123 ++---------------- .../guides/operations/cluster/manual.html.md | 6 +- .../consul-integration/index.html.md | 61 ++++++--- .../source/guides/operations/federation.md | 8 +- .../source/guides/operations/index.html.md | 13 ++ .../guides/operations/install/index.html.md | 4 +- .../monitoring/nomad-metrics.html.md | 2 +- .../operations/monitoring/telemetry.html.md | 8 +- .../guides/operations/node-draining.html.md | 16 +-- .../guides/operations/outage.html.markdown | 12 +- .../guides/operations/requirements.html.md | 8 +- .../guides/operations/upgrade/index.html.md | 14 +- .../upgrade/upgrade-specific.html.md | 22 ++-- .../vault-integration/index.html.md | 10 +- 18 files changed, 144 insertions(+), 205 deletions(-) create mode 100644 website/source/guides/operations/index.html.md diff --git a/website/source/guides/operations/agent/index.html.md b/website/source/guides/operations/agent/index.html.md index d98bcbd43..96ea43f15 100644 --- a/website/source/guides/operations/agent/index.html.md +++ b/website/source/guides/operations/agent/index.html.md @@ -1,7 +1,7 @@ --- -layout: "docs" +layout: "guides" page_title: "Nomad Agent" -sidebar_current: "docs-agent" +sidebar_current: "guides-operations-agent" description: |- The Nomad agent is a long running process which can be used either in a client or server mode. diff --git a/website/source/guides/operations/autopilot.html.md b/website/source/guides/operations/autopilot.html.md index fc5f5b434..2219e2059 100644 --- a/website/source/guides/operations/autopilot.html.md +++ b/website/source/guides/operations/autopilot.html.md @@ -1,7 +1,7 @@ --- layout: "guides" page_title: "Autopilot" -sidebar_current: "guides-autopilot" +sidebar_current: "guides-operations-autopilot" description: |- This guide covers how to configure and use Autopilot features. --- @@ -13,15 +13,15 @@ operator-friendly management of Nomad servers. It includes cleanup of dead servers, monitoring the state of the Raft cluster, and stable server introduction. To enable Autopilot features (with the exception of dead server cleanup), -the `raft_protocol` setting in the [server stanza](/docs/agent/configuration/server.html) +the `raft_protocol` setting in the [server stanza](/docs/configuration/server.html) must be set to 3 on all servers. In Nomad 0.8 this setting defaults to 2; in Nomad 0.9 it will default to 3. -For more information, see the [Version Upgrade section](/docs/upgrade/upgrade-specific.html#raft-protocol-version-compatibility) +For more information, see the [Version Upgrade section](/guides/operations/upgrade/upgrade-specific.html#raft-protocol-version-compatibility) on Raft Protocol versions. ## Configuration The configuration of Autopilot is loaded by the leader from the agent's -[Autopilot settings](/docs/agent/configuration/autopilot.html) when initially +[Autopilot settings](/docs/configuration/autopilot.html) when initially bootstrapping the cluster: ``` @@ -149,7 +149,7 @@ setting. ## Server Read and Scheduling Scaling -With the [`non_voting_server`](/docs/agent/configuration/server.html#non_voting_server) option, a +With the [`non_voting_server`](/docs/configuration/server.html#non_voting_server) option, a server can be explicitly marked as a non-voter and will never be promoted to a voting member. This can be useful when more read scaling is needed; being a non-voter means that the server will still have data replicated to it, but it will not be part of the @@ -164,7 +164,7 @@ have an overly-large quorum (2-3 nodes per AZ) or give up redundancy within an A deploying just one server in each. If the `EnableRedundancyZones` setting is set, Nomad will use its value to look for a -zone in each server's specified [`redundancy_zone`](/docs/agent/configuration/server.html#redundancy_zone) +zone in each server's specified [`redundancy_zone`](/docs/configuration/server.html#redundancy_zone) field. Here's an example showing how to configure this: @@ -216,6 +216,6 @@ a migration, so that the migration logic can be used for updating the cluster wh changing configuration. If the `EnableCustomUpgrades` setting is set to `true`, Nomad will use its value to look for a -version in each server's specified [`upgrade_version`](/docs/agent/configuration/server.html#upgrade_version) +version in each server's specified [`upgrade_version`](/docs/configuration/server.html#upgrade_version) tag. The upgrade logic will follow semantic versioning and the `upgrade_version` must be in the form of either `X`, `X.Y`, or `X.Y.Z`. diff --git a/website/source/guides/operations/cluster/automatic.html.md b/website/source/guides/operations/cluster/automatic.html.md index 1b7daaf27..8256473af 100644 --- a/website/source/guides/operations/cluster/automatic.html.md +++ b/website/source/guides/operations/cluster/automatic.html.md @@ -1,14 +1,14 @@ --- layout: "guides" -page_title: "Automatically Bootstrapping a Nomad Cluster" -sidebar_current: "guides-cluster-automatic" +page_title: "Automatic Clustering with Consul" +sidebar_current: "guides-operations-cluster-automatic" description: |- Learn how to automatically bootstrap a Nomad cluster using Consul. By having a Consul agent installed on each host, Nomad can automatically discover other clients and servers to bootstrap the cluster without operator involvement. --- -# Automatic Bootstrapping +# Automatic Clustering with Consul To automatically bootstrap a Nomad cluster, we must leverage another HashiCorp open source tool, [Consul](https://www.consul.io/). Bootstrapping Nomad is @@ -115,5 +115,5 @@ consul { ``` Please refer to the [Consul -documentation](/docs/agent/configuration/consul.html) for the complete set of +documentation](/docs/configuration/consul.html) for the complete set of configuration options. diff --git a/website/source/guides/operations/cluster/bootstrapping.html.md b/website/source/guides/operations/cluster/bootstrapping.html.md index 53d6541a5..62c122e1c 100644 --- a/website/source/guides/operations/cluster/bootstrapping.html.md +++ b/website/source/guides/operations/cluster/bootstrapping.html.md @@ -1,12 +1,12 @@ --- layout: "guides" -page_title: "Bootstrapping a Nomad Cluster" -sidebar_current: "guides-cluster-bootstrap" +page_title: "Clustering" +sidebar_current: "guides-operations-cluster" description: |- - Learn how to bootstrap a Nomad cluster. + Learn how to cluster Nomad. --- -# Bootstrapping a Nomad Cluster +# Clustering Nomad models infrastructure into regions and datacenters. Servers reside at the regional layer and manage all state and scheduling decisions for that region. @@ -15,10 +15,12 @@ datacenter (and thus a region that contains that datacenter). For more details o the architecture of Nomad and how it models infrastructure see the [architecture page](/docs/internals/architecture.html). -There are two strategies for bootstrapping a Nomad cluster: +There are multiple strategies available for creating a multi-node Nomad cluster: + +1. Manual Clustering +1. Automatic Clustering with Consul +1. Cloud Auto-join -1. Automatic bootstrapping -1. Manual bootstrapping Please refer to the specific documentation links above or in the sidebar for more detailed information about each strategy. diff --git a/website/source/guides/operations/cluster/cloud_auto_join.html.md b/website/source/guides/operations/cluster/cloud_auto_join.html.md index d733fe706..0825c77a4 100644 --- a/website/source/guides/operations/cluster/cloud_auto_join.html.md +++ b/website/source/guides/operations/cluster/cloud_auto_join.html.md @@ -1,24 +1,24 @@ --- -layout: "docs" +layout: "guides" page_title: "Cloud Auto-join" -sidebar_current: "docs-agent-cloud-auto-join" +sidebar_current: "guides-operations-cluster-cloud-auto-join" description: |- - Nomad supports automatic cluster joining using cloud metadata from various cloud providers + Nomad supports automatic cluster joining using cloud metadata from various + cloud providers --- # Cloud Auto-joining As of Nomad 0.8.4, -[`retry_join`](/docs/agent/configuration/server_join.html#retry_join) accepts a +[`retry_join`](/docs/configuration/server_join.html#retry_join) accepts a unified interface using the [go-discover](https://github.com/hashicorp/go-discover) library for doing automatic cluster joining using cloud metadata. To use retry-join with a supported cloud provider, specify the configuration on the command line or -configuration file as a `key=value key=value ...` string. - -Values are taken literally and must not be URL -encoded. If the values contain spaces, backslashes or double quotes then -they need to be double quoted and the usual escaping rules apply. +configuration file as a `key=value key=value ...` string. Values are taken +literally and must not be URL encoded. If the values contain spaces, backslashes +or double quotes thenthey need to be double quoted and the usual escaping rules +apply. ```json { @@ -26,111 +26,12 @@ they need to be double quoted and the usual escaping rules apply. } ``` -The cloud provider-specific configurations are detailed below. This can be -combined with static IP or DNS addresses or even multiple configurations -for different providers. - -In order to use discovery behind a proxy, you will need to set +The cloud provider-specific configurations are documented [here](/docs/configuration/server_join.html#cloud-auto-join). +This can be combined with static IP or DNS addresses or even multiple configurations +for different providers. In order to use discovery behind a proxy, you will need to set `HTTP_PROXY`, `HTTPS_PROXY` and `NO_PROXY` environment variables per [Golang `net/http` library](https://golang.org/pkg/net/http/#ProxyFromEnvironment). -The following sections give the options specific to a subset of supported cloud -provider. For information on all providers, see further documentation in -[go-discover](https://github.com/hashicorp/go-discover). - -### Amazon EC2 - -This returns the first private IP address of all servers in the given -region which have the given `tag_key` and `tag_value`. -```json -{ - "retry_join": ["provider=aws tag_key=... tag_value=..."] -} -``` - -- `provider` (required) - the name of the provider ("aws" in this case). -- `tag_key` (required) - the key of the tag to auto-join on. -- `tag_value` (required) - the value of the tag to auto-join on. -- `region` (optional) - the AWS region to authenticate in. -- `addr_type` (optional) - the type of address to discover: `private_v4`, `public_v4`, `public_v6`. Default is `private_v4`. (>= 1.0) -- `access_key_id` (optional) - the AWS access key for authentication (see below for more information about authenticating). -- `secret_access_key` (optional) - the AWS secret access key for authentication (see below for more information about authenticating). - -#### Authentication & Precedence - -- Static credentials `access_key_id=... secret_access_key=...` -- Environment variables (`AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY`) -- Shared credentials file (`~/.aws/credentials` or the path specified by `AWS_SHARED_CREDENTIALS_FILE`) -- ECS task role metadata (container-specific). -- EC2 instance role metadata. - - The only required IAM permission is `ec2:DescribeInstances`, and it is - recommended that you make a dedicated key used only for auto-joining. If the - region is omitted it will be discovered through the local instance's [EC2 - metadata - endpoint](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instance-identity-documents.html). - -### Microsoft Azure - - This returns the first private IP address of all servers in the given region - which have the given `tag_key` and `tag_value` in the tenant and subscription, or in - the given `resource_group` of a `vm_scale_set` for Virtual Machine Scale Sets. - - - ```json -{ - "retry_join": ["provider=azure tag_name=... tag_value=... tenant_id=... client_id=... subscription_id=... secret_access_key=..."] -} -``` - -- `provider` (required) - the name of the provider ("azure" in this case). -- `tenant_id` (required) - the tenant to join machines in. -- `client_id` (required) - the client to authenticate with. -- `secret_access_key` (required) - the secret client key. - -Use these configuration parameters when using tags: -- `tag_name` - the name of the tag to auto-join on. -- `tag_value` - the value of the tag to auto-join on. - -Use these configuration parameters when using Virtual Machine Scale Sets (Consul 1.0.3 and later): -- `resource_group` - the name of the resource group to filter on. -- `vm_scale_set` - the name of the virtual machine scale set to filter on. - - When using tags the only permission needed is the `ListAll` method for `NetworkInterfaces`. When using - Virtual Machine Scale Sets the only role action needed is `Microsoft.Compute/virtualMachineScaleSets/*/read`. - -### Google Compute Engine - -This returns the first private IP address of all servers in the given -project which have the given `tag_value`. -``` - -```json -{ -"retry_join": ["provider=gce project_name=... tag_value=..."] -} -``` - -- `provider` (required) - the name of the provider ("gce" in this case). -- `tag_value` (required) - the value of the tag to auto-join on. -- `project_name` (optional) - the name of the project to auto-join on. Discovered if not set. -- `zone_pattern` (optional) - the list of zones can be restricted through an RE2 compatible regular expression. If omitted, servers in all zones are returned. -- `credentials_file` (optional) - the credentials file for authentication. See below for more information. - -#### Authentication & Precedence - -- Use credentials from `credentials_file`, if provided. -- Use JSON file from `GOOGLE_APPLICATION_CREDENTIALS` environment variable. -- Use JSON file in a location known to the gcloud command-line tool. -- On Windows, this is `%APPDATA%/gcloud/application_default_credentials.json`. -- On other systems, `$HOME/.config/gcloud/application_default_credentials.json`. -- On Google Compute Engine, use credentials from the metadata -server. In this final case any provided scopes are ignored. - -Discovery requires a [GCE Service -Account](https://cloud.google.com/compute/docs/access/service-accounts). -Credentials are searched using the following paths, in order of precedence. - diff --git a/website/source/guides/operations/cluster/manual.html.md b/website/source/guides/operations/cluster/manual.html.md index cddd390dc..11eff1ac2 100644 --- a/website/source/guides/operations/cluster/manual.html.md +++ b/website/source/guides/operations/cluster/manual.html.md @@ -1,14 +1,14 @@ --- layout: "guides" -page_title: "Manually Bootstrapping a Nomad Cluster" -sidebar_current: "guides-cluster-manual" +page_title: "Manually Clustering" +sidebar_current: "guides-operations-cluster-manual" description: |- Learn how to manually bootstrap a Nomad cluster using the server join command. This section also discusses Nomad federation across multiple datacenters and regions. --- -# Manual Bootstrapping +# Manual Clustering Manually bootstrapping a Nomad cluster does not rely on additional tooling, but does require operator participation in the cluster formation process. When diff --git a/website/source/guides/operations/consul-integration/index.html.md b/website/source/guides/operations/consul-integration/index.html.md index 0547dd96c..a27e669a5 100644 --- a/website/source/guides/operations/consul-integration/index.html.md +++ b/website/source/guides/operations/consul-integration/index.html.md @@ -1,35 +1,58 @@ --- -layout: "docs" -page_title: "Service Discovery" -sidebar_current: "docs-service-discovery" +layout: "guides" +page_title: "Consul Integration" +sidebar_current: "guides-operations-consul-integration" description: |- - Learn how to add service discovery to jobs + Learn how to integrate Nomad with Consul and add service discovery to jobs --- -# Service Discovery +# Consul Integration + +[Consul][] is a tool for discovering and configuring services in your +infrastructure. Consul's key features include service discover, health checking, +a KV store, and robust support for multi-datacenter deployments. Nomad's integration +with Consul enables automatic clustering, built-in service registration, and +dynamic rendering of configuration files and environment variables. The sections +below describe the integration in more detail. + +## Configuration + +In order to use Consul with Nomad, you will need to configure and +install Consul on your nodes alongside Nomad, or schedule it as a system job. +Nomad does not currently run Consul for you. + +To enable Consul integration, please see the +[Nomad agent Consul integration](/docs/configuration/consul.html) +configuration. + +## Automatic Clustering with Consul + +Nomad servers and clients will be automatically informed of each other's +existence when a running Consul cluster already exists and the Consul agent is +installed and configured on each host. Please see the [Automatic Clustering with +Consul](/guides/operations/cluster/automatic.html) guide for more information. + +## Service Discovery Nomad schedules workloads of various types across a cluster of generic hosts. Because of this, placement is not known in advance and you will need to use service discovery to connect tasks to other services deployed across your -cluster. Nomad integrates with [Consul][] to provide service discovery and +cluster. Nomad integrates with Consul to provide service discovery and monitoring. -Note that in order to use Consul with Nomad, you will need to configure and -install Consul on your nodes alongside Nomad, or schedule it as a system job. -Nomad does not currently run Consul for you. - -## Configuration - -To enable Consul integration, please see the -[Nomad agent Consul integration](/docs/agent/configuration/consul.html) -configuration. - - -## Service Definition Syntax - To configure a job to register with service discovery, please see the [`service` job specification documentation][service]. +## Dynamic Configuration + +Nomad's job specification includes a [`template` stanza](/docs/job-specification/template.html) +that utilizes a Consul ecosystem tool called [Consul Template](https://github.com/hashicorp/consul-template). This mechanism creates a convenient way to ship configuration files +that are populated from environment variables, Consul data, Vault secrets, or just +general configurations within a Nomad task. + +For more information on Nomad's template stanza and how it leverages Consul Template, +please see the [`template` job specification documentation](/docs/job-specification/template.html). + ## Assumptions - Consul 0.7.2 or later is needed for `tls_skip_verify` in HTTP checks. diff --git a/website/source/guides/operations/federation.md b/website/source/guides/operations/federation.md index 4d1760df9..436b0957d 100644 --- a/website/source/guides/operations/federation.md +++ b/website/source/guides/operations/federation.md @@ -1,13 +1,13 @@ --- layout: "guides" -page_title: "Federating a Nomad Cluster" -sidebar_current: "guides-cluster-federation" +page_title: "Multi-region Federation" +sidebar_current: "guides-operations-federation" description: |- Learn how to join Nomad servers across multiple regions so users can submit jobs to any server in any region using global federation. --- -# Federating a Cluster +# Multi-region Federation Because Nomad operates at a regional level, federation is part of Nomad core. Federation enables users to submit jobs or interact with the HTTP API targeting @@ -33,4 +33,4 @@ enough to join just one known server. If bootstrapped via Consul and the Consul clusters in the Nomad regions are federated, then federation occurs automatically. -[ports]: /guides/cluster/requirements.html#ports-used +[ports]: /guides/operations/requirements.html#ports-used diff --git a/website/source/guides/operations/index.html.md b/website/source/guides/operations/index.html.md new file mode 100644 index 000000000..82403fa74 --- /dev/null +++ b/website/source/guides/operations/index.html.md @@ -0,0 +1,13 @@ +--- +layout: "guides" +page_title: "Nomad Operations" +sidebar_current: "guides-operations" +description: |- + Learn how to operate Nomad. +--- + +# Nomad Operations + +The Nomad Operations guides section provides best practices and guidance for +operating Nomad in a real-world production setting. Please navigate the +appropriate sub-sections for more information. \ No newline at end of file diff --git a/website/source/guides/operations/install/index.html.md b/website/source/guides/operations/install/index.html.md index efc25197b..c47a76a06 100644 --- a/website/source/guides/operations/install/index.html.md +++ b/website/source/guides/operations/install/index.html.md @@ -1,7 +1,7 @@ --- -layout: "docs" +layout: "guides" page_title: "Installing Nomad" -sidebar_current: "docs-installing" +sidebar_current: "guides-operations-installing" description: |- Learn how to install Nomad. --- diff --git a/website/source/guides/operations/monitoring/nomad-metrics.html.md b/website/source/guides/operations/monitoring/nomad-metrics.html.md index 6401297a6..bdd655a4e 100644 --- a/website/source/guides/operations/monitoring/nomad-metrics.html.md +++ b/website/source/guides/operations/monitoring/nomad-metrics.html.md @@ -1,7 +1,7 @@ --- layout: "guides" page_title: "Setting up Nomad with Grafana and Prometheus Metrics" -sidebar_current: "guides-nomad-metrics" +sidebar_current: "guides-operations-monitoring-grafana" description: |- It is possible to collect metrics on Nomad and create dashboards with Grafana and Prometheus. Nomad has default configurations for these, but it is diff --git a/website/source/guides/operations/monitoring/telemetry.html.md b/website/source/guides/operations/monitoring/telemetry.html.md index 43643a282..88fc0d4fc 100644 --- a/website/source/guides/operations/monitoring/telemetry.html.md +++ b/website/source/guides/operations/monitoring/telemetry.html.md @@ -1,7 +1,7 @@ --- -layout: "docs" +layout: "guides" page_title: "Telemetry" -sidebar_current: "docs-agent-telemetry" +sidebar_current: "guides-operations-monitoring-telemetry" description: |- Learn about the telemetry data available in Nomad. --- @@ -30,7 +30,7 @@ Telemetry information can be streamed to both [statsite](https://github.com/armo as well as statsd based on providing the appropriate configuration options. To configure the telemetry output please see the [agent -configuration](/docs/agent/configuration/telemetry.html). +configuration](/docs/configuration/telemetry.html). Below is sample output of a telemetry dump: @@ -233,7 +233,7 @@ By default the collection interval is 1 second but it can be changed by the changing the value of the `collection_interval` key in the `telemetry` configuration block. -Please see the [agent configuration](/docs/agent/configuration/telemetry.html) +Please see the [agent configuration](/docs/configuration/telemetry.html) page for more details. As of Nomad 0.9, Nomad will emit additional labels for [parameterized](/docs/job-specification/parameterized.html) and diff --git a/website/source/guides/operations/node-draining.html.md b/website/source/guides/operations/node-draining.html.md index 17afbb816..8f0f74d79 100644 --- a/website/source/guides/operations/node-draining.html.md +++ b/website/source/guides/operations/node-draining.html.md @@ -1,20 +1,20 @@ --- layout: "guides" -page_title: "Decommissioning Nodes" -sidebar_current: "guides-decommissioning-nodes" +page_title: "Workload Migration" +sidebar_current: "guides-operations-decommissioning-nodes" description: |- - Decommissioning nodes is a normal part of cluster operations for a variety of + Workload migration is a normal part of cluster operations for a variety of reasons: server maintenance, operating system upgrades, etc. Nomad offers a number of parameters for controlling how running jobs are migrated off of draining nodes. --- -# Decommissioning Nomad Client Nodes +# Workload Migration -Decommissioning nodes is a normal part of cluster operations for a variety of -reasons: server maintenance, operating system upgrades, etc. Nomad offers a -number of parameters for controlling how running jobs are migrated off of -draining nodes. +Migrating workloads and decommissioning nodes are a normal part of cluster +operations for a variety of reasons: server maintenance, operating system +upgrades, etc. Nomad offers a number of parameters for controlling how running +jobs are migrated off of draining nodes. ## Configuring How Jobs are Migrated diff --git a/website/source/guides/operations/outage.html.markdown b/website/source/guides/operations/outage.html.markdown index 22b9267e2..74aacfe58 100644 --- a/website/source/guides/operations/outage.html.markdown +++ b/website/source/guides/operations/outage.html.markdown @@ -1,7 +1,7 @@ --- layout: "guides" page_title: "Outage Recovery" -sidebar_current: "guides-outage-recovery" +sidebar_current: "guides-operations-outage-recovery" description: |- Don't panic! This is a critical first step. Depending on your deployment configuration, it may take only a single server failure for cluster @@ -20,15 +20,15 @@ requires an operator to intervene, but the process is straightforward. ~> This guide is for recovery from a Nomad outage due to a majority of server nodes in a datacenter being lost. If you are looking to add or remove servers, -see the [bootstrapping guide](/guides/cluster/bootstrapping.html). +see the [bootstrapping guide](/guides/operations/cluster/bootstrapping.html). ## Failure of a Single Server Cluster If you had only a single server and it has failed, simply restart it. A single server configuration requires the -[`-bootstrap-expect=1`](/docs/agent/configuration/server.html#bootstrap_expect) +[`-bootstrap-expect=1`](/docs/configuration/server.html#bootstrap_expect) flag. If the server cannot be recovered, you need to bring up a new -server. See the [bootstrapping guide](/guides/cluster/bootstrapping.html) +server. See the [bootstrapping guide](/guides/operations/cluster/bootstrapping.html) for more detail. In the case of an unrecoverable server failure in a single server cluster, data @@ -126,7 +126,7 @@ any automated processes that will put the peers file in place on a periodic basis. The next step is to go to the -[`-data-dir`](/docs/agent/configuration/index.html#data_dir) of each Nomad +[`-data-dir`](/docs/configuration/index.html#data_dir) of each Nomad server. Inside that directory, there will be a `raft/` sub-directory. We need to create a `raft/peers.json` file. It should look something like: @@ -220,5 +220,5 @@ Nomad server in the cluster, like this: server's RPC port used for cluster communications. - `non_voter` `(bool: )` - This controls whether the server is a non-voter, which is used - in some advanced [Autopilot](/guides/autopilot.html) configurations. If omitted, it will + in some advanced [Autopilot](/guides/operations/autopilot.html) configurations. If omitted, it will default to false, which is typical for most clusters. diff --git a/website/source/guides/operations/requirements.html.md b/website/source/guides/operations/requirements.html.md index b38af402c..7a06501ba 100644 --- a/website/source/guides/operations/requirements.html.md +++ b/website/source/guides/operations/requirements.html.md @@ -1,13 +1,13 @@ --- layout: "guides" -page_title: "Nomad Client and Server Requirements" -sidebar_current: "guides-cluster-requirements" +page_title: "Hardware Requirements" +sidebar_current: "guides-operations-requirements" description: |- Learn about Nomad client and server requirements such as memory and CPU recommendations, network topologies, and more. --- -# Cluster Requirements +# Hardware Requirements ## Resources (RAM, CPU, etc.) @@ -29,7 +29,7 @@ used by Nomad. This should be used to target a specific resource utilization per node and to reserve resources for applications running outside of Nomad's supervision such as Consul and the operating system itself. -Please see the [reservation configuration](/docs/agent/configuration/client.html#reserved) for +Please see the [reservation configuration](/docs/configuration/client.html#reserved) for more detail. ## Network Topology diff --git a/website/source/guides/operations/upgrade/index.html.md b/website/source/guides/operations/upgrade/index.html.md index 758f20a25..5128e3196 100644 --- a/website/source/guides/operations/upgrade/index.html.md +++ b/website/source/guides/operations/upgrade/index.html.md @@ -1,12 +1,12 @@ --- -layout: "docs" +layout: "guides" page_title: "Upgrading" -sidebar_current: "docs-upgrade-upgrading" +sidebar_current: "guides-operations-upgrade" description: |- Learn how to upgrade Nomad. --- -# Upgrading Nomad +# Upgrading This page documents how to upgrade Nomad when a new version is released. @@ -23,7 +23,7 @@ For upgrades we strive to ensure backwards compatibility. For most upgrades, the process is as simple as upgrading the binary and restarting the service. Prior to starting the upgrade please check the -[specific version details](/docs/upgrade/upgrade-specific.html) page as some +[specific version details](/guides/operations/upgrade/upgrade-specific.html) page as some version differences may require specific steps. At a high level we complete the following steps to upgrade Nomad: @@ -102,8 +102,8 @@ Use the same actions in step #2 above to confirm cluster health. Following the successful upgrade of the servers you can now update your clients using a similar process as the servers. You may either upgrade clients -in-place or start new nodes on the new version. See the [Decommissioning Nodes -guide](/guides/node-draining.html) for instructions on how to migrate running +in-place or start new nodes on the new version. See the [Workload Migration +Guide](/guides/operations/node-draining.html) for instructions on how to migrate running allocations from the old nodes to the new nodes with the [`nomad node drain`](/docs/commands/node/drain.html) command. @@ -118,5 +118,5 @@ are in a `ready` state. The process of upgrading to a Nomad Enterprise version is identical to upgrading between versions of open source Nomad. The same guidance above should be followed and as always, prior to starting the upgrade please check the [specific -version details](/docs/upgrade/upgrade-specific.html) page as some version +version details](/guides/operations/upgrade/upgrade-specific.html) page as some version differences may require specific steps. diff --git a/website/source/guides/operations/upgrade/upgrade-specific.html.md b/website/source/guides/operations/upgrade/upgrade-specific.html.md index 41897bce7..778124221 100644 --- a/website/source/guides/operations/upgrade/upgrade-specific.html.md +++ b/website/source/guides/operations/upgrade/upgrade-specific.html.md @@ -1,15 +1,15 @@ --- -layout: "docs" +layout: "guides" page_title: "Upgrade Guides" -sidebar_current: "docs-upgrade-specific" +sidebar_current: "guides-operations-upgrade-specific" description: |- Specific versions of Nomad may have additional information about the upgrade process beyond the standard flow. --- -# Upgrading Specific Versions +# Upgrade Guides -The [upgrading page](/docs/upgrade/index.html) covers the details of doing +The [upgrading page](/guides/operations/upgrade/index.html) covers the details of doing a standard upgrade. However, specific versions of Nomad may have more details provided for their upgrades as a result of new features or changed behavior. This page is used to document those details separately from the @@ -21,7 +21,7 @@ standard upgrade flow. When upgrading to Nomad 0.8.0 from a version lower than 0.7.0, users will need to set the -[`raft_protocol`](/docs/agent/configuration/server.html#raft_protocol) option +[`raft_protocol`](/docs/configuration/server.html#raft_protocol) option in their `server` stanza to 1 in order to maintain backwards compatibility with the old servers during the upgrade. After the servers have been migrated to version 0.8.0, `raft_protocol` can be moved up to 2 and the servers restarted @@ -50,18 +50,18 @@ Raft Protocol versions supported by each Nomad version: -In order to enable all [Autopilot](/guides/autopilot.html) features, all servers +In order to enable all [Autopilot](/guides/operations/autopilot.html) features, all servers in a Nomad cluster must be running with Raft protocol version 3 or later. #### Upgrading to Raft Protocol 3 -This section provides details on upgrading to Raft Protocol 3 in Nomad 0.8 and higher. Raft protocol version 3 requires Nomad running 0.8.0 or newer on all servers in order to work. See [Raft Protocol Version Compatibility](/docs/upgrade/upgrade-specific.html#raft-protocol-version-compatibility) for more details. Also the format of `peers.json` used for outage recovery is different when running with the latest Raft protocol. See [Manual Recovery Using peers.json](/guides/outage.html#manual-recovery-using-peers-json) for a description of the required format. +This section provides details on upgrading to Raft Protocol 3 in Nomad 0.8 and higher. Raft protocol version 3 requires Nomad running 0.8.0 or newer on all servers in order to work. See [Raft Protocol Version Compatibility](/guides/operations/upgrade/upgrade-specific.html#raft-protocol-version-compatibility) for more details. Also the format of `peers.json` used for outage recovery is different when running with the latest Raft protocol. See [Manual Recovery Using peers.json](/guides/operations/outage.html#manual-recovery-using-peers-json) for a description of the required format. Please note that the Raft protocol is different from Nomad's internal protocol as shown in commands like `nomad server members`. To see the version of the Raft protocol in use on each server, use the `nomad operator raft list-peers` command. The easiest way to upgrade servers is to have each server leave the cluster, upgrade its `raft_protocol` version in the `server` stanza, and then add it back. Make sure the new server joins successfully and that the cluster is stable before rolling the upgrade forward to the next server. It's also possible to stand up a new set of servers, and then slowly stand down each of the older servers in a similar fashion. -When using Raft protocol version 3, servers are identified by their `node-id` instead of their IP address when Nomad makes changes to its internal Raft quorum configuration. This means that once a cluster has been upgraded with servers all running Raft protocol version 3, it will no longer allow servers running any older Raft protocol versions to be added. If running a single Nomad server, restarting it in-place will result in that server not being able to elect itself as a leader. To avoid this, either set the Raft protocol back to 2, or use [Manual Recovery Using peers.json](/guides/outage.html#manual-recovery-using-peers-json) to map the server to its node ID in the Raft quorum configuration. +When using Raft protocol version 3, servers are identified by their `node-id` instead of their IP address when Nomad makes changes to its internal Raft quorum configuration. This means that once a cluster has been upgraded with servers all running Raft protocol version 3, it will no longer allow servers running any older Raft protocol versions to be added. If running a single Nomad server, restarting it in-place will result in that server not being able to elect itself as a leader. To avoid this, either set the Raft protocol back to 2, or use [Manual Recovery Using peers.json](/guides/operations/outage.html#manual-recovery-using-peers-json) to map the server to its node ID in the Raft quorum configuration. ### Node Draining Improvements @@ -78,7 +78,7 @@ The `drain` command now blocks until the drain completes. To get the Nomad -force -detach ` See the [`migrate` stanza documentation][migrate] and [Decommissioning Nodes -guide](/guides/node-draining.html) for details. +guide](/guides/operations/node-draining.html) for details. ### Periods in Environment Variable Names No Longer Escaped @@ -124,7 +124,7 @@ as the old style will be deprecated in future versions of Nomad. ### RPC Advertise Address The behavior of the [advertised RPC -address](/docs/agent/configuration/index.html#rpc-1) has changed to be only used +address](/docs/configuration/index.html#rpc-1) has changed to be only used to advertise the RPC address of servers to client nodes. Server to server communication is done using the advertised Serf address. Existing cluster's should not be effected but the advertised RPC address may need to be updated to @@ -149,7 +149,7 @@ If you manually configure `advertise` addresses no changes are necessary. The change to the default, advertised IP also effect clients that do not specify which network_interface to use. If you have several routable IPs, it is advised to configure the client's [network -interface](https://www.nomadproject.io/docs/agent/configuration/client.html#network_interface) +interface](/docs/configuration/client.html#network_interface) such that tasks bind to the correct address. ## Nomad 0.5.5 diff --git a/website/source/guides/operations/vault-integration/index.html.md b/website/source/guides/operations/vault-integration/index.html.md index 80df28f66..d4b53278e 100644 --- a/website/source/guides/operations/vault-integration/index.html.md +++ b/website/source/guides/operations/vault-integration/index.html.md @@ -1,9 +1,9 @@ --- -layout: "docs" +layout: "guides" page_title: "Vault Integration" -sidebar_current: "docs-vault-integration" +sidebar_current: "guides-operations-vault-integration" description: |- - Learn how to integrate with HashiCorp Vault and retrieve Vault tokens for + Learn how to integrate Nomad with HashiCorp Vault and retrieve Vault tokens for tasks. --- @@ -341,8 +341,8 @@ You can see examples of `v1` and `v2` syntax in the [auth]: https://www.vaultproject.io/docs/auth/token.html "Vault Authentication Backend" -[config]: /docs/agent/configuration/vault.html "Nomad Vault Configuration Block" -[createfromrole]: /docs/agent/configuration/vault.html#create_from_role "Nomad vault create_from_role Configuration Flag" +[config]: /docs/configuration/vault.html "Nomad Vault Configuration Block" +[createfromrole]: /docs/configuration/vault.html#create_from_role "Nomad vault create_from_role Configuration Flag" [template]: /docs/job-specification/template.html "Nomad template Job Specification" [vault]: https://www.vaultproject.io/ "Vault by HashiCorp" [vault-spec]: /docs/job-specification/vault.html "Nomad Vault Job Specification" From 8ae384dac7afd65a8de7774616e80578423abc73 Mon Sep 17 00:00:00 2001 From: Rob Genova Date: Fri, 22 Jun 2018 20:54:10 +0000 Subject: [PATCH 11/16] Update guides/operating-a-job --- website/source/guides/operating-a-job/index.html.md | 6 +++--- .../guides/operating-a-job/resource-utilization.html.md | 3 +-- 2 files changed, 4 insertions(+), 5 deletions(-) diff --git a/website/source/guides/operating-a-job/index.html.md b/website/source/guides/operating-a-job/index.html.md index e4f6cf58a..c29a20faf 100644 --- a/website/source/guides/operating-a-job/index.html.md +++ b/website/source/guides/operating-a-job/index.html.md @@ -1,12 +1,12 @@ --- layout: "guides" -page_title: "Operating a Job" +page_title: "Job Lifecycle" sidebar_current: "guides-operating-a-job" description: |- - Learn how to operate a Nomad Job. + Learn how to deploy and manage a Nomad Job. --- -# Operating a Job +# Job Lifecycle The general flow for operating a job in Nomad is: diff --git a/website/source/guides/operating-a-job/resource-utilization.html.md b/website/source/guides/operating-a-job/resource-utilization.html.md index e3a699327..c1d13041e 100644 --- a/website/source/guides/operating-a-job/resource-utilization.html.md +++ b/website/source/guides/operating-a-job/resource-utilization.html.md @@ -83,8 +83,7 @@ While single point in time resource usage measurements are useful, it is often more useful to graph resource usage over time to better understand and estimate resource usage. Nomad supports outputting resource data to statsite and statsd and is the recommended way of monitoring resources. For more information about -outputting telemetry see the [telemetry -documentation](/docs/agent/telemetry.html). +outputting telemetry see the [Telemetry Guide](/guides/operations/monitoring/telemetry.html). For more advanced use cases, the resource usage data is also accessible via the client's HTTP API. See the documentation of the Client's [allocation HTTP From 1ebdcf7688245de14888744cfcda29d4e8a609c1 Mon Sep 17 00:00:00 2001 From: Rob Genova Date: Fri, 22 Jun 2018 20:54:48 +0000 Subject: [PATCH 12/16] Update guides/security --- .../source/guides/security/acl.html.markdown | 20 +++++++++---------- .../source/guides/security/encryption.html.md | 14 ++++++------- website/source/guides/security/index.html.md | 13 ++++++++++++ .../guides/security/namespaces.html.markdown | 12 +++++------ website/source/guides/security/quotas.html.md | 8 ++++---- .../guides/security/securing-nomad.html.md | 18 ++++++++--------- .../security/sentinel-policy.html.markdown | 14 ++++++------- .../guides/security/sentinel/job.html.md | 2 +- 8 files changed, 57 insertions(+), 44 deletions(-) create mode 100644 website/source/guides/security/index.html.md diff --git a/website/source/guides/security/acl.html.markdown b/website/source/guides/security/acl.html.markdown index 89b0bf1c6..15ed4b11f 100644 --- a/website/source/guides/security/acl.html.markdown +++ b/website/source/guides/security/acl.html.markdown @@ -1,14 +1,14 @@ --- layout: "guides" -page_title: "ACLs" -sidebar_current: "guides-acl" +page_title: "Access Control" +sidebar_current: "guides-security-acl" description: |- Nomad provides an optional Access Control List (ACL) system which can be used to control access to data and APIs. The ACL is Capability-based, relying on tokens which are associated with policies to determine which fine grained rules can be applied. --- -# ACL System +# Access Control Nomad provides an optional Access Control List (ACL) system which can be used to control access to data and APIs. The ACL is [Capability-based](https://en.wikipedia.org/wiki/Capability-based_security), relying on tokens which are associated with policies to determine which fine grained rules can be applied. Nomad's capability based ACL system is very similar to the design of [AWS IAM](https://aws.amazon.com/iam/). @@ -56,15 +56,15 @@ Constructing rules from these policies is covered in detail in the Rule Specific Nomad supports multi-datacenter and multi-region configurations. A single region is able to service multiple datacenters, and all servers in a region replicate their state between each other. In a multi-region configuration, there is a set of servers per region. Each region operates independently and is loosely coupled to allow jobs to be scheduled in any region and requests to flow transparently to the correct region. -When ACLs are enabled, Nomad depends on an "authoritative region" to act as a single source of truth for ACL policies and global ACL tokens. The authoritative region is configured in the [`server` stanza](/docs/agent/configuration/server.html) of agents, and all regions must share a single authoritative source. Any ACL policies or global ACL tokens are created in the authoritative region first. All other regions replicate ACL policies and global ACL tokens to act as local mirrors. This allows policies to be administered centrally, and for enforcement to be local to each region for low latency. +When ACLs are enabled, Nomad depends on an "authoritative region" to act as a single source of truth for ACL policies and global ACL tokens. The authoritative region is configured in the [`server` stanza](/docs/configuration/server.html) of agents, and all regions must share a single authoritative source. Any ACL policies or global ACL tokens are created in the authoritative region first. All other regions replicate ACL policies and global ACL tokens to act as local mirrors. This allows policies to be administered centrally, and for enforcement to be local to each region for low latency. Global ACL tokens are used to allow cross region requests. Standard ACL tokens are created in a single target region and not replicated. This means if a request takes place between regions, global tokens must be used so that both regions will have the token registered. # Configuring ACLs -ACLs are not enabled by default, and must be enabled. Clients and Servers need to set `enabled` in the [`acl` stanza](/docs/agent/configuration/acl.html). This enables the [ACL Policy](/api/acl-policies.html) and [ACL Token](/api/acl-tokens.html) APIs, as well as endpoint enforcement. +ACLs are not enabled by default, and must be enabled. Clients and Servers need to set `enabled` in the [`acl` stanza](/docs/configuration/acl.html). This enables the [ACL Policy](/api/acl-policies.html) and [ACL Token](/api/acl-tokens.html) APIs, as well as endpoint enforcement. -For multi-region configurations, all servers must be configured to use a single [authoritative region](/docs/agent/configuration/server.html#authoritative_region). The authoritative region is responsible for managing ACL policies and global tokens. Servers in other regions will replicate policies and global tokens to act as a mirror, and must have their [`replication_token`](/docs/agent/configuration/acl.html#replication_token) configured. +For multi-region configurations, all servers must be configured to use a single [authoritative region](/docs/configuration/server.html#authoritative_region). The authoritative region is responsible for managing ACL policies and global tokens. Servers in other regions will replicate policies and global tokens to act as a mirror, and must have their [`replication_token`](/docs/configuration/acl.html#replication_token) configured. # Bootstrapping ACLs @@ -74,9 +74,9 @@ Bootstrapping ACLs on a new cluster requires a few steps, outlined below: The APIs needed to manage policies and tokens are not enabled until ACLs are enabled. To begin, we need to enable the ACLs on the servers. If a multi-region setup is used, the authoritative region should be enabled first. For each server: -1. Set `enabled = true` in the [`acl` stanza](/docs/agent/configuration/acl.html#enabled). -1. Set `authoritative_region` in the [`server` stanza](/docs/agent/configuration/server.html#authoritative_region). -1. For servers outside the authoritative region, set `replication_token` in the [`acl` stanza](/docs/agent/configuration/acl.html#replication_token). Replication tokens should be `management` type tokens which are either created in the authoritative region, or created as Global tokens. +1. Set `enabled = true` in the [`acl` stanza](/docs/configuration/acl.html#enabled). +1. Set `authoritative_region` in the [`server` stanza](/docs/configuration/server.html#authoritative_region). +1. For servers outside the authoritative region, set `replication_token` in the [`acl` stanza](/docs/configuration/acl.html#replication_token). Replication tokens should be `management` type tokens which are either created in the authoritative region, or created as Global tokens. 1. Restart the Nomad server to pick up the new configuration. Please take care to restart the servers one at a time, and ensure each server has joined and is operating correctly before restarting another. @@ -103,7 +103,7 @@ The bootstrap token is a `management` type token, meaning it can perform any ope ### Enable ACLs on Nomad Clients -To enforce client endpoints, we need to enable ACLs on clients as well. This is simpler than servers, and we just need to set `enabled = true` in the [`acl` stanza](/docs/agent/configuration/acl.html). Once configured, we need to restart the client for the change. +To enforce client endpoints, we need to enable ACLs on clients as well. This is simpler than servers, and we just need to set `enabled = true` in the [`acl` stanza](/docs/configuration/acl.html). Once configured, we need to restart the client for the change. ### Set an Anonymous Policy (Optional) diff --git a/website/source/guides/security/encryption.html.md b/website/source/guides/security/encryption.html.md index 2ddeb97a7..1854a9dc9 100644 --- a/website/source/guides/security/encryption.html.md +++ b/website/source/guides/security/encryption.html.md @@ -1,12 +1,12 @@ --- -layout: "docs" -page_title: "Gossip and RPC Encryption" -sidebar_current: "docs-agent-encryption" +layout: "guides" +page_title: "Encryption Overview" +sidebar_current: "guides-security-encryption" description: |- Learn how to configure Nomad to encrypt HTTP, RPC, and Serf traffic. --- -# Encryption +# Encryption Overview The Nomad agent supports encrypting all of its network traffic. There are two separate encryption systems, one for gossip traffic, and one for HTTP and @@ -16,7 +16,7 @@ RPC. Enabling gossip encryption only requires that you set an encryption key when starting the Nomad server. The key can be set via the -[`encrypt`](/docs/agent/configuration/server.html#encrypt) parameter: the value +[`encrypt`](/docs/configuration/server.html#encrypt) parameter: the value of this setting is a server configuration file containing the encryption key. The key must be 16 bytes, base64 encoded. As a convenience, Nomad provides the @@ -88,5 +88,5 @@ as it is unable to use client certificates. Read the [Securing Nomad with TLS Guide][guide] for details on how to configure encryption for Nomad. -[guide]: /guides/securing-nomad.html "Securing Nomad with TLS" -[tls]: /docs/agent/configuration/tls.html "Nomad TLS Configuration" +[guide]: /guides/security/securing-nomad.html "Securing Nomad with TLS" +[tls]: /docs/configuration/tls.html "Nomad TLS Configuration" diff --git a/website/source/guides/security/index.html.md b/website/source/guides/security/index.html.md new file mode 100644 index 000000000..761bfd641 --- /dev/null +++ b/website/source/guides/security/index.html.md @@ -0,0 +1,13 @@ +--- +layout: "guides" +page_title: "Security and Governance" +sidebar_current: "guides-security" +description: |- + Learn how to use Nomad safely and securely in a multi-team setting. +--- + +# Security and Governance + +The Nomad Security and Governance guides section provides best practices and +guidance for operating Nomad safely and securely in a multi-team setting. Please +navigate the appropriate sub-sections for more information. \ No newline at end of file diff --git a/website/source/guides/security/namespaces.html.markdown b/website/source/guides/security/namespaces.html.markdown index 40d3a69c7..2dd60605f 100644 --- a/website/source/guides/security/namespaces.html.markdown +++ b/website/source/guides/security/namespaces.html.markdown @@ -1,7 +1,7 @@ --- layout: "guides" page_title: "Namespaces" -sidebar_current: "guides-namespaces" +sidebar_current: "guides-security-namespaces" description: |- Nomad Enterprise provides support for namespaces, which allow jobs and their associated objects to be segmented from each other and other users of the @@ -27,7 +27,7 @@ When combined with ACLs, the isolation of namespaces can be enforced, only allowing designated users access to read or modify the jobs and associated objects in a namespace. -When [resource quotas](/guides/quotas.html) are applied to a namespace they +When [resource quotas](/guides/security/quotas.html) are applied to a namespace they provide a means to limit resource consumption by the jobs in the namespace. This can prevent a single actor from consuming excessive cluster resources and negatively impacting other teams and applications sharing the cluster. @@ -38,9 +38,9 @@ Nomad places all jobs and their derived objects into namespaces. These include jobs, allocations, deployments, and evaluations. Nomad does not namespace objects that are shared across multiple namespaces. -This includes nodes, [ACL policies](/guides/acl.html), [Sentinel -policies](/guides/sentinel-policy.html), and [quota -specifications](/guides/quotas.html). +This includes nodes, [ACL policies](/guides/security/acl.html), [Sentinel +policies](/guides/security/sentinel-policy.html), and [quota +specifications](/guides/security/quotas.html). ## Working with Namespaces @@ -104,7 +104,7 @@ rails-www service 50 running 09/17/17 19:17:46 UTC ### ACLs -Access to namespaces can be restricted using [ACLs](/guides/acl.html). As an +Access to namespaces can be restricted using [ACLs](/guides/security/acl.html). As an example we could create an ACL policy that allows full access to the QA environment for our web namespaces but restrict the production access by creating the following policy: diff --git a/website/source/guides/security/quotas.html.md b/website/source/guides/security/quotas.html.md index c6397b34e..b741b0693 100644 --- a/website/source/guides/security/quotas.html.md +++ b/website/source/guides/security/quotas.html.md @@ -1,7 +1,7 @@ --- layout: "guides" page_title: "Resource Quotas" -sidebar_current: "guides-quotas" +sidebar_current: "guides-security-quotas" description: |- Nomad Enterprise provides support for resource quotas, which allow operators to restrict the aggregate resource usage of namespaces. @@ -21,7 +21,7 @@ This is not present in the open source version of Nomad. When many teams or users are sharing Nomad clusters, there is the concern that a single user could use more than their fair share of resources. Resource quotas provide a mechanism for cluster administrators to restrict the resources that a -[namespace](/guides/namespaces.html) has access to. +[namespace](/guides/security/namespaces.html) has access to. ## Quotas Objects @@ -172,7 +172,7 @@ allocation since that would cause the quota to be oversubscribed on memory. ### ACLs -Access to quotas can be restricted using [ACLs](/guides/acl.html). As an +Access to quotas can be restricted using [ACLs](/guides/security/acl.html). As an example we could create an ACL policy that allows read-only access to quotas. ``` @@ -201,7 +201,7 @@ When specifying resource limits the following enforcement behaviors are defined: Nomad makes working with quotas in a federated cluster simple by replicating quota specifications from the [authoritative Nomad -region](/docs/agent/configuration/server.html#authoritative_region). This allows +region](/docs/configuration/server.html#authoritative_region). This allows operators to interact with a single cluster but create quota specifications that apply to all Nomad clusters. diff --git a/website/source/guides/security/securing-nomad.html.md b/website/source/guides/security/securing-nomad.html.md index 98fdd1a2f..8b5198c6e 100644 --- a/website/source/guides/security/securing-nomad.html.md +++ b/website/source/guides/security/securing-nomad.html.md @@ -1,7 +1,7 @@ --- layout: "guides" page_title: "Securing Nomad with TLS" -sidebar_current: "guides-securing-nomad" +sidebar_current: "guides-security-tls" description: |- Securing Nomad's cluster communication with TLS is important for both security and easing operations. Nomad can use mutual TLS (mTLS) for @@ -352,7 +352,7 @@ not use TLS: Nomad server's gossip protocol use a shared key instead of TLS for encryption. This encryption key must be added to every server's configuration using the -[`encrypt`](/docs/agent/configuration/server.html#encrypt) parameter or with +[`encrypt`](/docs/configuration/server.html#encrypt) parameter or with the [`-encrypt` command line option](/docs/commands/agent.html). The Nomad CLI includes a `operator keygen` command for generating a new secure gossip @@ -499,16 +499,16 @@ connections) once the entire cluster has been migrated. [cfssl]: https://cfssl.org/ [cfssl.json]: https://raw.githubusercontent.com/hashicorp/nomad/master/demo/vagrant/cfssl.json -[guide-install]: https://www.nomadproject.io/intro/getting-started/install.html -[guide-cluster]: https://www.nomadproject.io/intro/getting-started/cluster.html +[guide-install]: /intro/getting-started/install.html +[guide-cluster]: /intro/getting-started/cluster.html [guide-server]: https://raw.githubusercontent.com/hashicorp/nomad/master/demo/vagrant/server.hcl -[heartbeat_grace]: /docs/agent/configuration/server.html#heartbeat_grace +[heartbeat_grace]: /docs/configuration/server.html#heartbeat_grace [letsencrypt]: https://letsencrypt.org/ -[rpc_upgrade_mode]: https://www.nomadproject.io/docs/agent/configuration/tls.html#rpc_upgrade_mode/ +[rpc_upgrade_mode]: /docs/configuration/tls.html#rpc_upgrade_mode/ [tls]: https://en.wikipedia.org/wiki/Transport_Layer_Security -[tls_block]: /docs/agent/configuration/tls.html +[tls_block]: /docs/configuration/tls.html [vagrantfile]: https://raw.githubusercontent.com/hashicorp/nomad/master/demo/vagrant/Vagrantfile [vault]: https://www.vaultproject.io/ [vault-pki]: https://www.vaultproject.io/docs/secrets/pki/index.html -[verify_https_client]: /docs/agent/configuration/tls.html#verify_https_client -[verify_server_hostname]: /docs/agent/configuration/tls.html#verify_server_hostname +[verify_https_client]: /docs/configuration/tls.html#verify_https_client +[verify_server_hostname]: /docs/configuration/tls.html#verify_server_hostname diff --git a/website/source/guides/security/sentinel-policy.html.markdown b/website/source/guides/security/sentinel-policy.html.markdown index ee7ff3e2f..728fba5cd 100644 --- a/website/source/guides/security/sentinel-policy.html.markdown +++ b/website/source/guides/security/sentinel-policy.html.markdown @@ -1,14 +1,14 @@ --- layout: "guides" page_title: "Sentinel Policies" -sidebar_current: "guides-sentinel" +sidebar_current: "guides-security-sentinel" description: |- Nomad integrates with Sentinel for fine-grained policy enforcement. Sentinel allows operators to express their policies as code, and have their policies automatically enforced. This allows operators to define a "sandbox" and restrict actions to only those compliant with policy. The Sentinel integration builds on the ACL System. --- # Sentinel Policies -[Nomad Enterprise](https://www.hashicorp.com/products/nomad/) integrates with [HashiCorp Sentinel](https://docs.hashicorp.com/sentinel) for fine-grained policy enforcement. Sentinel allows operators to express their policies as code, and have their policies automatically enforced. This allows operators to define a "sandbox" and restrict actions to only those compliant with policy. The Sentinel integration builds on the [ACL System](/guides/acl.html). +[Nomad Enterprise](/docs/enterprise/index.html) integrates with [HashiCorp Sentinel](https://docs.hashicorp.com/sentinel) for fine-grained policy enforcement. Sentinel allows operators to express their policies as code, and have their policies automatically enforced. This allows operators to define a "sandbox" and restrict actions to only those compliant with policy. The Sentinel integration builds on the [ACL System](/guides/security/acl.html). ~> **Enterprise Only!** This functionality only exists in Nomad Enterprise. This is not present in the open source version of Nomad. @@ -55,23 +55,23 @@ The following table summarizes the enforcement levels that are available: | soft-mandatory | Prevents operation when a policy fails, issues a warning if overridden | | hard-mandatory | Prevents operation when a policy fails | -The [`sentinel-override` capability](/guides/acl.html#sentinel-override) is required to override a `soft-mandatory` policy. This allows a restricted set of users to have override capability when necessary. +The [`sentinel-override` capability](/guides/security/acl.html#sentinel-override) is required to override a `soft-mandatory` policy. This allows a restricted set of users to have override capability when necessary. ## Multi-Region Configuration Nomad supports multi-datacenter and multi-region configurations. A single region is able to service multiple datacenters, and all servers in a region replicate their state between each other. In a multi-region configuration, there is a set of servers per region. Each region operates independently and is loosely coupled to allow jobs to be scheduled in any region and requests to flow transparently to the correct region. -When ACLs are enabled, Nomad depends on an "authoritative region" to act as a single source of truth for ACL policies, global ACL tokens, and Sentinel policies. The authoritative region is configured in the [`server` stanza](/docs/agent/configuration/server.html) of agents, and all regions must share a single authoritative source. Any Sentinel policies are created in the authoritative region first. All other regions replicate Sentinel policies, ACL policies, and global ACL tokens to act as local mirrors. This allows policies to be administered centrally, and for enforcement to be local to each region for low latency. +When ACLs are enabled, Nomad depends on an "authoritative region" to act as a single source of truth for ACL policies, global ACL tokens, and Sentinel policies. The authoritative region is configured in the [`server` stanza](/docs/configuration/server.html) of agents, and all regions must share a single authoritative source. Any Sentinel policies are created in the authoritative region first. All other regions replicate Sentinel policies, ACL policies, and global ACL tokens to act as local mirrors. This allows policies to be administered centrally, and for enforcement to be local to each region for low latency. ## Configuring Sentinel Policies Sentinel policies are tied to the ACL system, which is not enabled by default. -See the [ACL guide](/guides/acl.html) for details on how to configure ACLs. +See the [ACL guide](/guides/security/acl.html) for details on how to configure ACLs. ## Example: Installing Sentinel Policies This example shows how to install a Sentinel policy. It assumes that ACLs have already -been bootstrapped (see the [ACL guide](/guides/acl.html)), and that a `NOMAD_TOKEN` environment variable +been bootstrapped (see the [ACL guide](/guides/security/acl.html)), and that a `NOMAD_TOKEN` environment variable is set to a management token. First, create a Sentinel policy, named `test.sentinel`: @@ -205,5 +205,5 @@ The following objects are made available in the `submit-job` scope: | ------ | ------------------------- | | `job` | The job being submitted | -See the [Sentinel Job Object](/guides/sentinel/job.html) for details on the fields that are available. +See the [Sentinel Job Object](/guides/security/sentinel/job.html) for details on the fields that are available. diff --git a/website/source/guides/security/sentinel/job.html.md b/website/source/guides/security/sentinel/job.html.md index 868e7d59e..c9f2b9669 100644 --- a/website/source/guides/security/sentinel/job.html.md +++ b/website/source/guides/security/sentinel/job.html.md @@ -1,7 +1,7 @@ --- layout: "guides" page_title: "Sentinel Job Object" -sidebar_current: "guides-sentinel-job" +sidebar_current: "guides-security-sentinel-job" description: |- Job objects can be introspected to apply fine grained Sentinel policies. --- From 2e5f483dc23bc14b094498b48451b4bf572e20ba Mon Sep 17 00:00:00 2001 From: Rob Genova Date: Fri, 22 Jun 2018 20:55:12 +0000 Subject: [PATCH 13/16] Update guides/spark --- website/source/guides/spark/configuration.html.md | 10 +++++----- website/source/guides/spark/hdfs.html.md | 2 +- website/source/guides/spark/monitoring.html.md | 4 ++-- website/source/guides/spark/spark.html.md | 2 +- 4 files changed, 9 insertions(+), 9 deletions(-) diff --git a/website/source/guides/spark/configuration.html.md b/website/source/guides/spark/configuration.html.md index 929861be9..cd0438253 100644 --- a/website/source/guides/spark/configuration.html.md +++ b/website/source/guides/spark/configuration.html.md @@ -40,30 +40,30 @@ the first Nomad server contacted. - `spark.nomad.docker.email` `(string: nil)` - Specifies the email address to use when downloading the Docker image specified by [spark.nomad.dockerImage](#spark.nomad.dockerImage). See the -[Docker driver authentication](https://www.nomadproject.io/docs/drivers/docker.html#authentication) +[Docker driver authentication](/docs/drivers/docker.html#authentication) docs for more information. - `spark.nomad.docker.password` `(string: nil)` - Specifies the password to use when downloading the Docker image specified by [spark.nomad.dockerImage](#spark.nomad.dockerImage). See the -[Docker driver authentication](https://www.nomadproject.io/docs/drivers/docker.html#authentication) +[Docker driver authentication](/docs/drivers/docker.html#authentication) docs for more information. - `spark.nomad.docker.serverAddress` `(string: nil)` - Specifies the server address (domain/IP without the protocol) to use when downloading the Docker image specified by [spark.nomad.dockerImage](#spark.nomad.dockerImage). Docker Hub is used by default. See the -[Docker driver authentication](https://www.nomadproject.io/docs/drivers/docker.html#authentication) +[Docker driver authentication](/docs/drivers/docker.html#authentication) docs for more information. - `spark.nomad.docker.username` `(string: nil)` - Specifies the username to use when downloading the Docker image specified by [spark.nomad.dockerImage](#spark-nomad-dockerImage). See the -[Docker driver authentication](https://www.nomadproject.io/docs/drivers/docker.html#authentication) +[Docker driver authentication](/docs/drivers/docker.html#authentication) docs for more information. - `spark.nomad.dockerImage` `(string: nil)` - Specifies the `URL` for the -[Docker image](https://www.nomadproject.io/docs/drivers/docker.html#image) to +[Docker image](/docs/drivers/docker.html#image) to use to run Spark with Nomad's `docker` driver. When not specified, Nomad's `exec` driver will be used instead. diff --git a/website/source/guides/spark/hdfs.html.md b/website/source/guides/spark/hdfs.html.md index d7d95013b..a901412c2 100644 --- a/website/source/guides/spark/hdfs.html.md +++ b/website/source/guides/spark/hdfs.html.md @@ -117,7 +117,7 @@ DataNodes to generically reference the NameNode: ``` Another viable option for DataNode task group is to use a dedicated -[system](https://www.nomadproject.io/docs/runtime/schedulers.html#system) job. +[system](/docs/schedulers.html#system) job. This will deploy a DataNode to every client node in the system, which may or may not be desirable depending on your use case. diff --git a/website/source/guides/spark/monitoring.html.md b/website/source/guides/spark/monitoring.html.md index 2299e9650..69430664d 100644 --- a/website/source/guides/spark/monitoring.html.md +++ b/website/source/guides/spark/monitoring.html.md @@ -127,9 +127,9 @@ $ spark-submit \ Nomad clients collect the `stderr` and `stdout` of running tasks. The CLI or the HTTP API can be used to inspect logs, as documented in -[Accessing Logs](https://www.nomadproject.io/guides/operating-a-job/accessing-logs.html). +[Accessing Logs](/guides/operating-a-job/accessing-logs.html). In cluster mode, the `stderr` and `stdout` of the `driver` application can be -accessed in the same way. The [Log Shipper Pattern](https://www.nomadproject.io/guides/operating-a-job/accessing-logs.html#log-shipper-pattern) uses sidecar tasks to forward logs to a central location. This +accessed in the same way. The [Log Shipper Pattern](/guides/operating-a-job/accessing-logs.html#log-shipper-pattern) uses sidecar tasks to forward logs to a central location. This can be done using a job template as follows: ```hcl diff --git a/website/source/guides/spark/spark.html.md b/website/source/guides/spark/spark.html.md index c2ef5b0d2..856958ce4 100644 --- a/website/source/guides/spark/spark.html.md +++ b/website/source/guides/spark/spark.html.md @@ -10,7 +10,7 @@ description: |- Nomad is well-suited for analytical workloads, given its [performance characteristics](https://www.hashicorp.com/c1m/) and first-class support for -[batch scheduling](https://www.nomadproject.io/docs/runtime/schedulers.html). +[batch scheduling](/docs/schedulers.html). Apache Spark is a popular data processing engine/framework that has been architected to use third-party schedulers. The Nomad ecosystem includes a [fork of Apache Spark](https://github.com/hashicorp/nomad-spark) that natively From e5050a332fce1cf8b55a3cfee3ba75e8838006ee Mon Sep 17 00:00:00 2001 From: Rob Genova Date: Fri, 22 Jun 2018 20:55:57 +0000 Subject: [PATCH 14/16] Misc. /guides updates --- website/source/guides/getting-started.html.md | 15 ++ website/source/guides/ui.html.md | 2 +- website/source/layouts/guides.erb | 247 +++++++++++------- 3 files changed, 172 insertions(+), 92 deletions(-) create mode 100644 website/source/guides/getting-started.html.md diff --git a/website/source/guides/getting-started.html.md b/website/source/guides/getting-started.html.md new file mode 100644 index 000000000..53099ddba --- /dev/null +++ b/website/source/guides/getting-started.html.md @@ -0,0 +1,15 @@ +--- +layout: "guides" +page_title: "Getting Started" +sidebar_current: "guides-getting-started" +description: |- + This section takes you to the Getting Started section. +--- + +# Nomad Getting Started + +Welcome to the Nomad guides section! If you are just getting started with +Nomad, please start with the [Nomad introduction](/intro/getting-started/install.html) instead and then continue on to the guides. The guides provide examples of +common Nomad workflows and actions for developers, operators, and security teams. + + diff --git a/website/source/guides/ui.html.md b/website/source/guides/ui.html.md index d8c9f6b7b..d1c1fcdab 100644 --- a/website/source/guides/ui.html.md +++ b/website/source/guides/ui.html.md @@ -12,7 +12,7 @@ description: |- The Nomad Web UI offers an easy to use web experience for inspecting a Nomad cluster. Jobs, Deployments, Evaluations, Task Groups, Allocations, Logs, Clients, and Servers can all be monitored from the Web UI. The Web UI also supports the use of ACL tokens for -clusters that are using the [ACL system](/guides/acl.html). +clusters that are using the [ACL system](/guides/security/acl.html). ## Accessing the Web UI diff --git a/website/source/layouts/guides.erb b/website/source/layouts/guides.erb index 0707e652c..3a9207a0e 100644 --- a/website/source/layouts/guides.erb +++ b/website/source/layouts/guides.erb @@ -2,71 +2,12 @@ <% content_for :sidebar do %> - > - Outage Recovery - - - > - Resource Quotas - - - > - Securing Nomad - - - > - Sentinel Policies + > + Operations + + + > + Security and Governance + + + + > + Apache Spark Integration + From b6dc487a15531e466ba9981f3ebd10418fa1f992 Mon Sep 17 00:00:00 2001 From: Rob Genova Date: Fri, 22 Jun 2018 20:57:16 +0000 Subject: [PATCH 15/16] Add redirects and fix broken link in layouts/downloads.erb --- website/redirects.txt | 72 +++++++++++++++++++++++++--- website/source/layouts/downloads.erb | 2 +- 2 files changed, 66 insertions(+), 8 deletions(-) diff --git a/website/redirects.txt b/website/redirects.txt index a497aa62e..13a9b02ab 100644 --- a/website/redirects.txt +++ b/website/redirects.txt @@ -40,7 +40,7 @@ /community.html /resources.html # Docs -/docs/agent/config.html /docs/agent/configuration/index.html +/docs/agent/config.html /docs/configuration/index.html /docs/jobops /guides/operating-a-job/index.html /docs/jobops/ /guides/operating-a-job/index.html /docs/jobops/index.html /guides/operating-a-job/index.html @@ -49,20 +49,20 @@ /docs/jobops/resources.html /guides/operating-a-job/resource-utilization.html /docs/jobops/logs.html /guides/operating-a-job/accessing-logs.html /docs/jobops/updating.html /guides/operating-a-job/update-strategies/index.html -/docs/jobops/servicediscovery.html /docs/service-discovery/index.html +/docs/jobops/servicediscovery.html /guides/operations/consul-integration/index.html /docs/jobspec /docs/job-specification/index.html /docs/jobspec/ /docs/job-specification/index.html /docs/jobspec/index.html /docs/job-specification/index.html /docs/jobspec/interpreted.html /docs/runtime/interpolation.html /docs/jobspec/json.html /api/json-jobs.html /docs/jobspec/environment.html /docs/runtime/environment.html -/docs/jobspec/schedulers.html /docs/runtime/schedulers.html +/docs/jobspec/schedulers.html /docs/schedulers.html /docs/jobspec/servicediscovery.html /docs/job-specification/service.html /docs/jobspec/networking.html /docs/job-specification/network.html -/docs/cluster/automatic.html /guides/cluster/automatic.html -/docs/cluster/manual.html /guides/cluster/manual.html -/docs/cluster/federation.html /guides/cluster/federation.html -/docs/cluster/requirements.html /guides/cluster/requirements.html +/docs/cluster/automatic.html /guides/operations/cluster/automatic.html +/docs/cluster/manual.html /guides/operations/cluster/manual.html +/docs/cluster/federation.html /guides/operations/federation.html +/docs/cluster/requirements.html /guides/operations/requirements.html /docs/commands/operator-index.html /docs/commands/operator.html /docs/commands/operator-raft-list-peers.html /docs/commands/operator/raft-list-peers.html /docs/commands/operator-raft-remove-peer.html /docs/commands/operator/raft-remove-peer.html @@ -84,6 +84,7 @@ /docs/commands/server-force-leave.html /docs/commands/server/force-leave.html /docs/commands/server-join.html /docs/commands/server/join.html /docs/commands/server-members.html /docs/commands/server/members.html +/docs/runtime/schedulers.html /docs/schedulers.html # Moved /docs/operating-a-job/ -> /guides/operating-a-job/ /docs/operating-a-job /guides/operating-a-job/index.html @@ -109,6 +110,42 @@ /docs/operating-a-job/update-strategies/handling-signals.html /guides/operating-a-job/update-strategies/handling-signals.html /docs/operating-a-job/update-strategies/rolling-upgrades.html /guides/operating-a-job/update-strategies/rolling-upgrades.html +# Moved /docs/agent/configuration/ -> /docs/configuration/ + +/docs/agent/configuration /docs/configuration/index.html +/docs/agent/configuration/ /docs/configuration/index.html +/docs/agent/configuration/index.html /docs/configuration/index.html +/docs/agent/configuration/acl.html /docs/configuration/acl.html +/docs/agent/configuration/autopilot.html /docs/configuration/autopilot.html +/docs/agent/configuration/client.html /docs/configuration/client.html +/docs/agent/configuration/consul.html /docs/configuration/consul.html +/docs/agent/configuration/sentinel.html /docs/configuration/sentinel.html +/docs/agent/configuration/server.html /docs/configuration/server.html +/docs/agent/configuration/server_join.html /docs/configuration/server_join.html +/docs/agent/configuration/telemetry.html /docs/configuration/telemetry.html +/docs/agent/configuration/tls.html /docs/configuration/tls.html +/docs/agent/configuration/vault.html /docs/configuration/vault.html + +# Moved guide-like docs to /guides +/docs/agent /guides/operations/agent/index.html +/docs/agent/ /guides/operations/agent/index.html +/docs/agent/index.html /guides/operations/agent/index.html +/docs/agent/cloud_auto_join.html /guides/operations/cluster/cloud_auto_join.html +/docs/agent/telemetry.html /guides/operations/monitoring/telemetry.html +/docs/agent/encryption.html /guides/security/encryption.html +/docs/install /guides/operations/install/index.html +/docs/install/ /guides/operations/install/index.html +/docs/install/index.html /guides/operations/install/index.html +/docs/upgrade /guides/operations/upgrade/index.html +/docs/upgrade/ /guides/operations/upgrade/index.html +/docs/upgrade/index.html /guides/operations/upgrade/index.html +/docs/upgrade/upgrade-specific.html /guides/operations/upgrade/upgrade-specific.html +/docs/service-discovery /guides/operations/consul-integration/index.html +/docs/service-discovery/ /guides/operations/consul-integration/index.html +/docs/service-discovery/index.html /guides/operations/consul-integration/index.html +/docs/vault-integration /guides/operations/vault-integration/index.html +/docs/vault-integration/ /guides/operations/vault-integration/index.html +/docs/vault-integration/index.html /guides/operations/vault-integration/index.html # API /docs/http/index.html /api/index.html @@ -133,3 +170,24 @@ /docs/http/status.html /api/status.html /docs/http/operator.html /api/operator.html /docs/http/system.html /api/system.html + +# Guides + +# Reorganized Guides by Persona +/guides/autopilot.html /guides/operations/autopilot.html +/guides/cluster/automatic.html /guides/operations/cluster/automatic.html +/guides/cluster/bootstrapping.html /guides/operations/cluster/bootstrapping.html +/guides/cluster/manual.html /guides/operations/cluster/manual.html +/guides/cluster/federation /guides/operations/federation +/guides/cluster/requirements.html /guides/operations/requirements.html +/guides/nomad-metrics.html /guides/operations/monitoring/nomad-metrics.html +/guides/node-draining.html /guides/operations/node-draining.html +/guides/outage.html /guides/operations/outage.html +/guides/acl.html /guides/security/acl.html +/guides/namespaces.html /guides/security/namespaces.html +/guides/quotas.html /guides/security/quotas.html +/guides/securing-nomad.html /guides/security/securing-nomad.html +/guides/sentinel-policy.html /guides/security/sentinel-policy.html +/guides/sentinel/job.html /guides/security/sentinel/job.html + + diff --git a/website/source/layouts/downloads.erb b/website/source/layouts/downloads.erb index bbb682de6..fac9cb87b 100644 --- a/website/source/layouts/downloads.erb +++ b/website/source/layouts/downloads.erb @@ -6,7 +6,7 @@
  • - Build from Source + Build from Source
    • <% end %> From 9863449ff31039b8ddc501ba948e2897a745a0fd Mon Sep 17 00:00:00 2001 From: Preetha Appan Date: Mon, 27 Aug 2018 09:19:22 -0500 Subject: [PATCH 16/16] Minor wording change --- website/source/intro/vs/index.html.markdown | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/source/intro/vs/index.html.markdown b/website/source/intro/vs/index.html.markdown index 17de4ce26..6825da1bc 100644 --- a/website/source/intro/vs/index.html.markdown +++ b/website/source/intro/vs/index.html.markdown @@ -19,7 +19,7 @@ The following characteristics generally differentiate Nomad from related product * **Scalability and High Performance**: Nomad can schedule thousands of containers per second, scale to thousands of nodes in a single cluster, and easily federate across regions and cloud providers. -* **HashiCorp Synergy**: Nomad elegantly integrates with Vault for secrets +* **HashiCorp Interoperability**: Nomad elegantly integrates with Vault for secrets management and Consul for service discovery and dynamic configuration. Nomad's Consul-like architecture and Terraform-like job specification lower the barrier to entry for existing users of the HashiCorp stack.