From 7faa311fed42881ed8da67d71c6c5e2c03e638e4 Mon Sep 17 00:00:00 2001 From: Armon Dadgar Date: Tue, 22 Sep 2015 16:18:26 -0700 Subject: [PATCH] website: getting started --- .../source/intro/getting-started/apis.html.md | 21 --- .../intro/getting-started/cluster.html.md | 17 +++ .../source/intro/getting-started/http.html.md | 16 ++ .../source/intro/getting-started/jobs.html.md | 140 +++--------------- .../intro/getting-started/running.html.md | 2 +- 5 files changed, 55 insertions(+), 141 deletions(-) delete mode 100644 website/source/intro/getting-started/apis.html.md create mode 100644 website/source/intro/getting-started/cluster.html.md create mode 100644 website/source/intro/getting-started/http.html.md diff --git a/website/source/intro/getting-started/apis.html.md b/website/source/intro/getting-started/apis.html.md deleted file mode 100644 index 6863125f8..000000000 --- a/website/source/intro/getting-started/apis.html.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -layout: "intro" -page_title: "Using the HTTP APIs with Authentication" -sidebar_current: "getting-started-apis" -description: |- - Using the HTTP APIs for authentication and secret access. ---- - -# Using the HTTP APIs with Authentication -Many of Nomad's capabilities are accessible via the HTTP API in addition to the -CLI. - -TODO: Document Nomad's HTTP API - -Congratulations! You now know all the basics to get started with Nomad. - -## Next - -Next, we have a page dedicated to -[next steps](/intro/getting-started/next-steps.html) depending on -what you would like to achieve. diff --git a/website/source/intro/getting-started/cluster.html.md b/website/source/intro/getting-started/cluster.html.md new file mode 100644 index 000000000..3af9cc9ec --- /dev/null +++ b/website/source/intro/getting-started/cluster.html.md @@ -0,0 +1,17 @@ +--- +layout: "intro" +page_title: "Nomad Cluster" +sidebar_current: "getting-started-cluster" +description: |- + Join another Nomad client to create your first cluster. +--- + +# Nomad Cluster + +TODO: Document clustering + +## Next Steps + +We've now concluded the getting started guide, however there are a number +of [next steps](next-steps.html) to get started with Nomad. + diff --git a/website/source/intro/getting-started/http.html.md b/website/source/intro/getting-started/http.html.md new file mode 100644 index 000000000..2cf5df21a --- /dev/null +++ b/website/source/intro/getting-started/http.html.md @@ -0,0 +1,16 @@ +--- +layout: "intro" +page_title: "HTTP API" +sidebar_current: "getting-started-http" +description: |- + Learn about the HTTP APIs for interacting with Nomad. +--- + +# HTTP API + +TODO: Document Nomad's HTTP API + +## Next Steps + +Next we will add another Nomad client to [create our first cluster](cluster.html) + diff --git a/website/source/intro/getting-started/jobs.html.md b/website/source/intro/getting-started/jobs.html.md index 43415e4ea..0e8b034f5 100644 --- a/website/source/intro/getting-started/jobs.html.md +++ b/website/source/intro/getting-started/jobs.html.md @@ -3,137 +3,39 @@ layout: "intro" page_title: "Jobs" sidebar_current: "getting-started-jobs" description: |- - Learn how to deploy Nomad into production, how to initialize it, configure it, etc. + Learn how to submit, modify and stop jobs in Nomad. --- # Jobs -Nomad relies on a long running agent on every machine in the cluster. -The agent can run either in server or client mode. Each region must -have at least one server, though a cluster of 3 or 5 servers is recommended. -A single server deployment is _**highly**_ discouraged as data loss is inevitable -in a failure scenario. +Jobs are the primary configuration that users interact with when using +Nomad. A job is a declaritive specification of tasks that Nomad should run. +Jobs have a globally unique name, one or many task groups, which are themselves +collections of one or many tasks. -All other agents run in client mode. A client is a very lightweight -process that registers the host machine, performs heartbeating, and runs any tasks -that are assigned to it by the servers. The agent must be run on every node that -is part of the cluster so that the servers can assign work to those machines. +The format of the jobs is [documented here](/docs/jobspec/index.html). They +can either be specified in [HCL](https://github.com/hashicorp/hcl) or JSON, +however we recommend only using JSON when the configuration is generated by a machine. -## Starting the Agent - -For simplicity, we will run a single Nomad agent in development mode. This mode -is used to quickly start an agent that is acting as a client and server to test -job configurations or prototype interactions. It should _**not**_ be used in -production as it does not persist state. +To get started, we will use the [`init` command](/docs/commands/init.html) which +generates an skeleton job file: ``` -$ nomad agent -dev -==> Starting Nomad agent... -==> Nomad agent configuration: +$ nomad init +Created job file 'example.nomad' - Atlas: - Client: true - Log Level: debug - Region: global (DC: dc1) - Server: true +$ cat example.nomad -==> Nomad agent started! Log data will stream in below: - - [INFO] serf: EventMemberJoin: nomad.global 127.0.0.1 - [INFO] nomad: starting 4 scheduling worker(s) for [service batch _core] - [INFO] raft: Node at 127.0.0.1:4647 [Follower] entering Follower state - [INFO] nomad: adding server nomad.global (Addr: 127.0.0.1:4647) (DC: dc1) - [DEBUG] client: applied fingerprints [storage arch cpu host memory] - [DEBUG] client: available drivers [exec docker] - [WARN] raft: Heartbeat timeout reached, starting election - [INFO] raft: Node at 127.0.0.1:4647 [Candidate] entering Candidate state - [DEBUG] raft: Votes needed: 1 - [DEBUG] raft: Vote granted. Tally: 1 - [INFO] raft: Election won. Tally: 1 - [INFO] raft: Node at 127.0.0.1:4647 [Leader] entering Leader state - [INFO] raft: Disabling EnableSingleNode (bootstrap) - [DEBUG] raft: Node 127.0.0.1:4647 updated peer set (2): [127.0.0.1:4647] - [INFO] nomad: cluster leadership acquired - [DEBUG] client: node registration complete - [DEBUG] client: updated allocations at index 1 (0 allocs) - [DEBUG] client: allocs: (added 0) (removed 0) (updated 0) (ignore 0) - [DEBUG] client: state updated to ready -``` - -As you can see, the Nomad agent has started and has output some log -data. From the log data, you can see that our agent is running in both -client and server mode, and has claimed leadership of the cluster. -Additionally, the local client has been registered and marked as ready. - -## Cluster Nodes - -If you run [`nomad node-status`](/docs/commands/node-status.html) in another terminal, you -can see the registered nodes of the Nomad cluster: - -```text -$ vagrant ssh -... - -$ nomad node-status -ID DC Name Class Drain Status -72d3af97-144f-1e5f-94e5-df1516fe4add dc1 nomad false ready -``` - -The output shows our Node ID, which is randomly generated UUID, -it's datacenter, node name, node class, drain mode and current status. -We can see that our node is in the ready state, and task draining is -currently off. - -The agent is also running in server mode, which means it is part of -the [gossip protocol](/docs/internals/gossip.html) used to connect all -the server instances together. We can view the members of the gossip -ring using the [`server-members`](/docs/commands/server-members.html) command: - -```text -$ nomad server-members -Name Addr Port Status Proto Build DC Region -nomad.global 127.0.0.1 4648 alive 2 0.1.0dev dc1 global -``` - -The output shows our own agent, the address it is running on, its -health state, some version information, and the datacenter and region. -Additional metadata can be viewed by providing the `-detailed` flag. - -## Stopping the Agent - -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/config.html) to gracefully -leave on either the interrupt or terminate signals. - -After interrupting the agent, you should see it leave the cluster -and shut down: +job "example" { + region = "global" + datacenter = ["dc1", "dc2"] + ... +} ``` -^C==> Caught signal: interrupt - [DEBUG] http: Shutting down http server - [INFO] agent: requesting shutdown - [INFO] client: shutting down - [INFO] nomad: shutting down server - [WARN] serf: Shutdown without a Leave - [INFO] agent: shutdown complete -``` - -By gracefully leaving, Nomad clients update their status to prevent -futher tasks from being scheduled and to start migrating any tasks that are -already assigned. Nomad servers notifies other their peers they intend to leave. -When a server leaves, replication to that server stops. If a server fails, -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, a graceful leave is important to avoid -causing a potential availability outage affecting the -[consensus protocol](/docs/internals/consensus.html). If a server does -forcefully exit and will not be returning into service, the -[`server-force-leave` command](/docs/commands/server-force-leave.html) should -be used to force the server from a _failed_ to a _left_ state. ## Next Steps -The development Nomad agent is up and running. Let's try to [run a job](jobs.html)! +We've now covered the basic workflow around jobs with Nomad. Next +we will do a brief [tour of the HTTP API](http.html). + diff --git a/website/source/intro/getting-started/running.html.md b/website/source/intro/getting-started/running.html.md index eb7582617..5991aef05 100644 --- a/website/source/intro/getting-started/running.html.md +++ b/website/source/intro/getting-started/running.html.md @@ -3,7 +3,7 @@ layout: "intro" page_title: "Running Nomad" sidebar_current: "getting-started-running" description: |- - Learn how to deploy Nomad into production, how to initialize it, configure it, etc. + Learn about the Nomad agent, and the lifecycle of running and stopping. --- # Running Nomad