From 11f0d0fe3f762374d987ba7933556f8cc681027a Mon Sep 17 00:00:00 2001 From: "Gavin M. Roy" Date: Wed, 30 Apr 2014 15:26:07 -0400 Subject: [PATCH 1/2] Minor documentation fixes - Correct spotted typos - Ran JSON snippets through jsonpp for consistent display of JSON results - Unfortunately my editor stripped EOL whitespace so there's a bit of whitespace diff --- .../source/docs/agent/basics.html.markdown | 5 +- .../source/docs/agent/checks.html.markdown | 3 +- website/source/docs/agent/http.html.markdown | 280 +++++++++--------- .../source/docs/agent/options.html.markdown | 10 +- website/source/docs/agent/rpc.html.markdown | 3 +- 5 files changed, 154 insertions(+), 147 deletions(-) diff --git a/website/source/docs/agent/basics.html.markdown b/website/source/docs/agent/basics.html.markdown index 2324803d18..ba05f8a196 100644 --- a/website/source/docs/agent/basics.html.markdown +++ b/website/source/docs/agent/basics.html.markdown @@ -76,7 +76,7 @@ There are several important components that `consul agent` outputs: ## Stopping an Agent -An agent can be stoped in two ways: gracefully or forcefully. To gracefully +An agent can be stopped in two ways: gracefully or forcefully. To gracefully halt an agent, send the process an interrupt signal, which is usually `Ctrl-C` from a terminal. When gracefully exiting, the agent first notifies the cluster it intends to leave the cluster. This way, other cluster members @@ -88,7 +88,7 @@ eventually (usually within seconds) detect that the node has died and will notify the cluster that the node has _failed_. It is especially important that a server node be allowed to gracefully leave, -so that there will be a minimal impact on availablity as the server leaves +so that there will be a minimal impact on availability as the server leaves the consensus quorum. For client agents, the difference between a node _failing_ and a node _leaving_ @@ -96,4 +96,3 @@ may not be important for your use case. For example, for a web server and load balancer setup, both result in the same action: remove the web node from the load balancer pool. But for other situations, you may handle each scenario differently. - diff --git a/website/source/docs/agent/checks.html.markdown b/website/source/docs/agent/checks.html.markdown index 6c0c3fad4c..f344f0adfc 100644 --- a/website/source/docs/agent/checks.html.markdown +++ b/website/source/docs/agent/checks.html.markdown @@ -19,7 +19,7 @@ There are two different kinds of checks: every 30 seconds). This is similar to the Nagios plugin system. * TTL - These checks retain their last known state for a given TTL. The state - of the check must be updated periodicadically over the HTTP interface. If an + of the check must be updated periodically over the HTTP interface. If an external system fails to update the status within a given TTL, the check is set to the failed state. This mechanism is used to allow an application to directly report it's health. For example, a web app can periodically curl the @@ -79,4 +79,3 @@ a specific meaning. Specifically: This is the only convention that Consul depends on. Any output of the script will be captured and stored in the `notes` field so that it can be viewed by human operators. - diff --git a/website/source/docs/agent/http.html.markdown b/website/source/docs/agent/http.html.markdown index 4ea5501058..b5ab1cd5a2 100644 --- a/website/source/docs/agent/http.html.markdown +++ b/website/source/docs/agent/http.html.markdown @@ -101,11 +101,11 @@ Each object will look like: [ { - "CreateIndex":100, - "ModifyIndex":200, - "Key":"zip", - "Flags":0, - "Value":"dGVzdA==" + "CreateIndex": 100, + "ModifyIndex": 200, + "Key": "zip", + "Flags": 0, + "Value": "dGVzdA==" } ] @@ -182,15 +182,15 @@ anti-entropy, so in most situations everything will be in sync within a few seco This endpoint is hit with a GET and returns a JSON body like this: { - "service:redis":{ - "Node":"foobar", - "CheckID":"service:redis", - "Name":"Service 'redis' check", - "Status":"passing", - "Notes":"", + "service:redis": { + "Node": "foobar", + "CheckID": "service:redis", + "Name": "Service 'redis' check", + "Status": "passing", + "Notes": "", "Output": "", - "ServiceID":"redis", - "ServiceName":"redis" + "ServiceID": "redis", + "ServiceName": "redis" } } @@ -206,11 +206,11 @@ anti-entropy, so in most situations everything will be in sync within a few seco This endpoint is hit with a GET and returns a JSON body like this: { - "redis":{ - "ID":"redis", - "Service":"redis", - "Tags":null, - "Port":8000 + "redis": { + "ID": "redis", + "Service": "redis", + "Tags": null, + "Port": 8000 } } @@ -228,22 +228,22 @@ This endpoint returns a JSON body like: [ { - "Name":"foobar", - "Addr":"10.1.10.12", - "Port":8301, - "Tags":{ - "bootstrap":"1", - "dc":"dc1", - "port":"8300", - "role":"consul" + "Name": "foobar", + "Addr": "10.1.10.12", + "Port": 8301, + "Tags": { + "bootstrap": "1", + "dc": "dc1", + "port": "8300", + "role": "consul" }, - "Status":1, - "ProtocolMin":1, - "ProtocolMax":2, - "ProtocolCur":2, - "DelegateMin":1, - "DelegateMax":3, - "DelegateCur":3 + "Status": 1, + "ProtocolMin": 1, + "ProtocolMax": 2, + "ProtocolCur": 2, + "DelegateMin": 1, + "DelegateMax": 3, + "DelegateCur": 3 } ] @@ -268,7 +268,7 @@ The endpoint always returns 200. The register endpoint is used to add a new check to the local agent. There is more documentation on checks [here](/docs/agent/checks.html). -Checks are either a script or TTL type. The agent is reponsible for managing +Checks are either a script or TTL type. The agent is responsible for managing the status of the check and keeping the Catalog in sync. The register endpoint expects a JSON request body to be PUT. The request @@ -276,11 +276,11 @@ body must look like: { "ID": "mem", - "Name": "Memory utilization", - "Notes": "Ensure we don't oversubscribe memory", + "Name": "Memory utilization", + "Notes": "Ensure we don't oversubscribe memory", "Script": "/usr/local/bin/check_mem.py", - "Interval": "10s", - "TTL": "15s" + "Interval": 10, + "TTL": 15 } The `Name` field is mandatory, as is either `Script` and `Interval` @@ -332,7 +332,7 @@ The return code is 200 on success. The register endpoint is used to add a new service to the local agent. There is more documentation on services [here](/docs/agent/services.html). -Services may also provide a health check. The agent is reponsible for managing +Services may also provide a health check. The agent is responsible for managing the status of the check and keeping the Catalog in sync. The register endpoint expects a JSON request body to be PUT. The request @@ -340,13 +340,16 @@ body must look like: { "ID": "redis1", - "Name": "redis", - "Tags": ["master", "v1"], - "Port": 8000, + "Name": "redis", + "Tags": [ + "master", + "v1" + ], + "Port": 8000, "Check": { "Script": "/usr/local/bin/check_redis.py", - "Interval": "10s", - "TTL": "15s" + "Interval": 10, + "TTL": 15 } } @@ -402,8 +405,11 @@ body must look like: "Service": { "ID": "redis1", "Service": "redis", - "Tags": ["master", "v1"], - "Port": 8000, + "Tags": [ + "master", + "v1" + ], + "Port": 8000 }, "Check": { "Node": "foobar", @@ -501,12 +507,12 @@ It returns a JSON body like this: [ { - "Node":"baz", - "Address":"10.1.10.11" + "Node": "baz", + "Address": "10.1.10.11" }, { - "Node":"foobar", - "Address":"10.1.10.12" + "Node": "foobar", + "Address": "10.1.10.12" } ] @@ -521,9 +527,12 @@ however the dc can be provided using the "?dc=" query parameter. It returns a JSON body like this: { - "consul":[], - "redis":[], - "postgresql":["master","slave"] + "consul": [], + "redis": [], + "postgresql": [ + "master", + "slave" + ] } The main object keys are the service names, while the array @@ -545,12 +554,12 @@ It returns a JSON body like this: [ { - "Node":"foobar", - "Address":"10.1.10.12", - "ServiceID":"redis", - "ServiceName":"redis", - "ServiceTags":null, - "ServicePort":8000 + "Node": "foobar", + "Address": "10.1.10.12", + "ServiceID": "redis", + "ServiceName": "redis", + "ServiceTags": null, + "ServicePort": 8000 } ] @@ -566,22 +575,24 @@ The node being queried must be provided after the slash. It returns a JSON body like this: { - "Node":{ - "Node":"foobar", - "Address":"10.1.10.12" + "Node": { + "Node": "foobar", + "Address": "10.1.10.12" }, - "Services":{ - "consul":{ - "ID":"consul", - "Service":"consul", - "Tags":null, - "Port":8300 + "Services": { + "consul": { + "ID": "consul", + "Service": "consul", + "Tags": null, + "Port": 8300 }, - "redis":{ - "ID":"redis", - "Service":"redis", - "Tags":["v1"], - "Port":8000 + "redis": { + "ID": "redis", + "Service": "redis", + "Tags": [ + "v1" + ], + "Port": 8000 } } } @@ -590,7 +601,7 @@ This endpoint supports blocking queries and all consistency modes. ## Health -The Health used to query health related information. It is provided seperately +The Health used to query health related information. It is provided separately from the Catalog, since users may prefer to not use the health checking mechanisms as they are totally optional. Additionally, some of the query results from the Health system are filtered, while the Catalog endpoints provide the raw entries. @@ -614,24 +625,24 @@ It returns a JSON body like this: [ { - "Node":"foobar", - "CheckID":"serfHealth", - "Name":"Serf Health Status", - "Status":"passing", - "Notes":"", + "Node": "foobar", + "CheckID": "serfHealth", + "Name": "Serf Health Status", + "Status": "passing", + "Notes": "", "Output": "", - "ServiceID":"", - "ServiceName":"" + "ServiceID": "", + "ServiceName": "" }, { - "Node":"foobar", - "CheckID":"service:redis", - "Name":"Service 'redis' check", - "Status":"passing", - "Notes":"", + "Node": "foobar", + "CheckID": "service:redis", + "Name": "Service 'redis' check", + "Status": "passing", + "Notes": "", "Output": "", - "ServiceID":"redis", - "ServiceName":"redis" + "ServiceID": "redis", + "ServiceName": "redis" } ] @@ -656,14 +667,14 @@ It returns a JSON body like this: [ { - "Node":"foobar", - "CheckID":"service:redis", - "Name":"Service 'redis' check", - "Status":"passing", - "Notes":"", + "Node": "foobar", + "CheckID": "service:redis", + "Name": "Service 'redis' check", + "Status": "passing", + "Notes": "", "Output": "", - "ServiceID":"redis", - "ServiceName":"redis" + "ServiceID": "redis", + "ServiceName": "redis" } ] @@ -696,35 +707,36 @@ It returns a JSON body like this: [ { - "Node":{ - "Node":"foobar", - "Address":"10.1.10.12" + "Node": { + "Node": "foobar", + "Address": "10.1.10.12" }, - "Service":{ - "ID":"redis", - "Service":"redis", - "Tags":null, - "Port":8000 + "Service": { + "ID": "redis", + "Service": "redis", + "Tags": null, + "Port": 8000 }, - "Checks":[ + "Checks": [ { - "Node":"foobar", - "CheckID":"service:redis", - "Name":"Service 'redis' check", - "Status":"passing", - "Notes":"", + "Node": "foobar", + "CheckID": "service:redis", + "Name": "Service 'redis' check", + "Status": "passing", + "Notes": "", "Output": "", - "ServiceID":"redis", - "ServiceName":"redis" - },{ - "Node":"foobar", - "CheckID":"serfHealth", - "Name":"Serf Health Status", - "Status":"passing", - "Notes":"", + "ServiceID": "redis", + "ServiceName": "redis" + }, + { + "Node": "foobar", + "CheckID": "serfHealth", + "Name": "Serf Health Status", + "Status": "passing", + "Notes": "", "Output": "", - "ServiceID":"", - "ServiceName":"" + "ServiceID": "", + "ServiceName": "" } ] } @@ -745,24 +757,24 @@ It returns a JSON body like this: [ { - "Node":"foobar", - "CheckID":"serfHealth", - "Name":"Serf Health Status", - "Status":"passing", - "Notes":"", + "Node": "foobar", + "CheckID": "serfHealth", + "Name": "Serf Health Status", + "Status": "passing", + "Notes": "", "Output": "", - "ServiceID":"", - "ServiceName":"" + "ServiceID": "", + "ServiceName": "" }, { - "Node":"foobar", - "CheckID":"service:redis", - "Name":"Service 'redis' check", - "Status":"passing", - "Notes":"", + "Node": "foobar", + "CheckID": "service:redis", + "Name": "Service 'redis' check", + "Status": "passing", + "Notes": "", "Output": "", - "ServiceID":"redis", - "ServiceName":"redis" + "ServiceID": "redis", + "ServiceName": "redis" } ] @@ -792,5 +804,3 @@ This endpoint is used to get the Raft peers for the datacenter the agent is running in. It returns a list of addresses like: ["10.1.10.12:8300", "10.1.10.11:8300", "10.1.10.10:8300"] - - diff --git a/website/source/docs/agent/options.html.markdown b/website/source/docs/agent/options.html.markdown index b98d5a4d31..e9fa123848 100644 --- a/website/source/docs/agent/options.html.markdown +++ b/website/source/docs/agent/options.html.markdown @@ -28,8 +28,8 @@ The options below are all specified on the command-line. * `-bootstrap` - This flag is used to control if a server is in "bootstrap" mode. It is important that no more than one server *per* datacenter be running in this mode. The initial server **must** be in bootstrap - mode. Technically, a server in boostrap mode is allowed to self-elect as the Raft leader. It is important - that only a single node is in this mode, because otherwise consistency cannot be guarenteed if multiple + mode. Technically, a server in bootstrap mode is allowed to self-elect as the Raft leader. It is important + that only a single node is in this mode, because otherwise consistency cannot be guaranteed if multiple nodes are able to self-elect. Once there are multiple servers in a datacenter, it is generally a good idea to disable bootstrap mode on all of them. @@ -88,7 +88,7 @@ The options below are all specified on the command-line. * `-server` - This flag is used to control if an agent is in server or client mode. When provided, an agent will act as a Consul server. Each Consul cluster must have at least one server, and ideally no more than 5 *per* datacenter. All servers participate in the Raft consensus algorithm, to ensure that - transactions occur in a consistent, linearlizable manner. Transactions modify cluster state, which + transactions occur in a consistent, linearizable manner. Transactions modify cluster state, which is maintained on all server nodes to ensure availability in the case of node failure. Server nodes also participate in a WAN gossip pool with server nodes in other datacenters. Servers act as gateways to other datacenters and forward traffic as appropriate. @@ -158,7 +158,8 @@ definitions support being updated during a reload. Must be provided along with the `key_file`. * `domain` - By default, Consul responds to DNS queries in the "consul." domain. - This flag can be used to change that domain. All queries in this domain are assumed to be handled by Consul, and will not be recursively resolved. + This flag can be used to change that domain. All queries in this domain are assumed + to be handled by Consul, and will not be recursively resolved. * `enable_debug` - When set, enables some additional debugging features. Currently, only used to set the runtime profiling HTTP endpoints. @@ -213,4 +214,3 @@ definitions support being updated during a reload. the Certificate Authority from the `ca_file`. By default, this is false, and Consul will not make use of TLS for outgoing connections. This applies to clients and servers, as both will make outgoing connections. - diff --git a/website/source/docs/agent/rpc.html.markdown b/website/source/docs/agent/rpc.html.markdown index 51e8dfc47c..a27c1ec39e 100644 --- a/website/source/docs/agent/rpc.html.markdown +++ b/website/source/docs/agent/rpc.html.markdown @@ -169,7 +169,7 @@ we may start getting messages like: {"Log": "2013/12/03 13:06:53 [INFO] agent: Received event: member-join"} ``` -It is important to realize that these messages are sent asyncronously, +It is important to realize that these messages are sent asynchronously, and not in response to any command. That means if a client is streaming commands, there may be logs streamed while a client is waiting for a response to a command. This is why the `Seq` must be used to pair requests @@ -214,4 +214,3 @@ There is no request body, the response body looks like: ... } ``` - From 2d62fb3207566e441be11eef0d8f85f6dc26f3b1 Mon Sep 17 00:00:00 2001 From: "Gavin M. Roy" Date: Wed, 30 Apr 2014 15:46:20 -0400 Subject: [PATCH 2/2] Revert the interval and TTL values --- website/source/docs/agent/http.html.markdown | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/website/source/docs/agent/http.html.markdown b/website/source/docs/agent/http.html.markdown index b5ab1cd5a2..d21a9644d1 100644 --- a/website/source/docs/agent/http.html.markdown +++ b/website/source/docs/agent/http.html.markdown @@ -279,8 +279,8 @@ body must look like: "Name": "Memory utilization", "Notes": "Ensure we don't oversubscribe memory", "Script": "/usr/local/bin/check_mem.py", - "Interval": 10, - "TTL": 15 + "Interval": "10s", + "TTL": "15s" } The `Name` field is mandatory, as is either `Script` and `Interval` @@ -348,8 +348,8 @@ body must look like: "Port": 8000, "Check": { "Script": "/usr/local/bin/check_redis.py", - "Interval": 10, - "TTL": 15 + "Interval": "10s", + "TTL": "15s" } }