luxolus
/
open-consul
2
0
Fork 0
Code Issues 1 Pull Requests Packages Releases Wiki Activity

Merge pull request #96 from gmr/master 

website: Minor documentation fixes
This commit is contained in:
Armon Dadgar 2014-04-30 12:48:05 -07:00
parent b54e1696f2 c90975405a
commit eae91804b6
5 changed files with 150 additions and 143 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
website/source/docs/agent/basics.html.markdown
View File

@ -76,7 +76,7 @@ There are several important components that `consul agent` outputs:
## Stopping an Agent ## 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 halt an agent, send the process an interrupt signal, which is usually
`Ctrl-C` from a terminal. When gracefully exiting, the agent first notifies `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 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_. notify the cluster that the node has _failed_.
It is especially important that a server node be allowed to gracefully leave, 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. the consensus quorum.
For client agents, the difference between a node _failing_ and a node _leaving_ 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 balancer setup, both result in the same action: remove the web node
from the load balancer pool. But for other situations, you may handle from the load balancer pool. But for other situations, you may handle
each scenario differently. each scenario differently.

3
website/source/docs/agent/checks.html.markdown
View File

@ -19,7 +19,7 @@ There are two different kinds of checks:
every 30 seconds). This is similar to the Nagios plugin system. 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 * 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 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 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 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 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 will be captured and stored in the `notes` field so that it can be viewed
by human operators. by human operators.

272
website/source/docs/agent/http.html.markdown
View File

@ -101,11 +101,11 @@ Each object will look like:
[ [
{ {
"CreateIndex":100, "CreateIndex": 100,
"ModifyIndex":200, "ModifyIndex": 200,
"Key":"zip", "Key": "zip",
"Flags":0, "Flags": 0,
"Value":"dGVzdA==" "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: This endpoint is hit with a GET and returns a JSON body like this:
{ {
"service:redis":{ "service:redis": {
"Node":"foobar", "Node": "foobar",
"CheckID":"service:redis", "CheckID": "service:redis",
"Name":"Service 'redis' check", "Name": "Service 'redis' check",
"Status":"passing", "Status": "passing",
"Notes":"", "Notes": "",
"Output": "", "Output": "",
"ServiceID":"redis", "ServiceID": "redis",
"ServiceName":"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: This endpoint is hit with a GET and returns a JSON body like this:
{ {
"redis":{ "redis": {
"ID":"redis", "ID": "redis",
"Service":"redis", "Service": "redis",
"Tags":null, "Tags": null,
"Port":8000 "Port": 8000
} }
} }
@ -228,22 +228,22 @@ This endpoint returns a JSON body like:
[ [
{ {
"Name":"foobar", "Name": "foobar",
"Addr":"10.1.10.12", "Addr": "10.1.10.12",
"Port":8301, "Port": 8301,
"Tags":{ "Tags": {
"bootstrap":"1", "bootstrap": "1",
"dc":"dc1", "dc": "dc1",
"port":"8300", "port": "8300",
"role":"consul" "role": "consul"
}, },
"Status":1, "Status": 1,
"ProtocolMin":1, "ProtocolMin": 1,
"ProtocolMax":2, "ProtocolMax": 2,
"ProtocolCur":2, "ProtocolCur": 2,
"DelegateMin":1, "DelegateMin": 1,
"DelegateMax":3, "DelegateMax": 3,
"DelegateCur":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. 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). 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 status of the check and keeping the Catalog in sync.
The register endpoint expects a JSON request body to be PUT. The request The register endpoint expects a JSON request body to be PUT. The request
@ -276,8 +276,8 @@ body must look like:
{ {
"ID": "mem", "ID": "mem",
"Name": "Memory utilization", "Name": "Memory utilization",
"Notes": "Ensure we don't oversubscribe memory", "Notes": "Ensure we don't oversubscribe memory",
"Script": "/usr/local/bin/check_mem.py", "Script": "/usr/local/bin/check_mem.py",
"Interval": "10s", "Interval": "10s",
"TTL": "15s" "TTL": "15s"
@ -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. 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). 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 status of the check and keeping the Catalog in sync.
The register endpoint expects a JSON request body to be PUT. The request The register endpoint expects a JSON request body to be PUT. The request
@ -340,9 +340,12 @@ body must look like:
{ {
"ID": "redis1", "ID": "redis1",
"Name": "redis", "Name": "redis",
"Tags": ["master", "v1"], "Tags": [
"Port": 8000, "master",
"v1"
],
"Port": 8000,
"Check": { "Check": {
"Script": "/usr/local/bin/check_redis.py", "Script": "/usr/local/bin/check_redis.py",
"Interval": "10s", "Interval": "10s",
@ -402,8 +405,11 @@ body must look like:
"Service": { "Service": {
"ID": "redis1", "ID": "redis1",
"Service": "redis", "Service": "redis",
"Tags": ["master", "v1"], "Tags": [
"Port": 8000, "master",
"v1"
],
"Port": 8000
}, },
"Check": { "Check": {
"Node": "foobar", "Node": "foobar",
@ -501,12 +507,12 @@ It returns a JSON body like this:
[ [
{ {
"Node":"baz", "Node": "baz",
"Address":"10.1.10.11" "Address": "10.1.10.11"
}, },
{ {
"Node":"foobar", "Node": "foobar",
"Address":"10.1.10.12" "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: It returns a JSON body like this:
{ {
"consul":[], "consul": [],
"redis":[], "redis": [],
"postgresql":["master","slave"] "postgresql": [
"master",
"slave"
]
} }
The main object keys are the service names, while the array The main object keys are the service names, while the array
@ -545,12 +554,12 @@ It returns a JSON body like this:
[ [
{ {
"Node":"foobar", "Node": "foobar",
"Address":"10.1.10.12", "Address": "10.1.10.12",
"ServiceID":"redis", "ServiceID": "redis",
"ServiceName":"redis", "ServiceName": "redis",
"ServiceTags":null, "ServiceTags": null,
"ServicePort":8000 "ServicePort": 8000
} }
] ]
@ -566,22 +575,24 @@ The node being queried must be provided after the slash.
It returns a JSON body like this: It returns a JSON body like this:
{ {
"Node":{ "Node": {
"Node":"foobar", "Node": "foobar",
"Address":"10.1.10.12" "Address": "10.1.10.12"
}, },
"Services":{ "Services": {
"consul":{ "consul": {
"ID":"consul", "ID": "consul",
"Service":"consul", "Service": "consul",
"Tags":null, "Tags": null,
"Port":8300 "Port": 8300
}, },
"redis":{ "redis": {
"ID":"redis", "ID": "redis",
"Service":"redis", "Service": "redis",
"Tags":["v1"], "Tags": [
"Port":8000 "v1"
],
"Port": 8000
} }
} }
} }
@ -590,7 +601,7 @@ This endpoint supports blocking queries and all consistency modes.
## Health ## 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 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. 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", "Node": "foobar",
"CheckID":"serfHealth", "CheckID": "serfHealth",
"Name":"Serf Health Status", "Name": "Serf Health Status",
"Status":"passing", "Status": "passing",
"Notes":"", "Notes": "",
"Output": "", "Output": "",
"ServiceID":"", "ServiceID": "",
"ServiceName":"" "ServiceName": ""
}, },
{ {
"Node":"foobar", "Node": "foobar",
"CheckID":"service:redis", "CheckID": "service:redis",
"Name":"Service 'redis' check", "Name": "Service 'redis' check",
"Status":"passing", "Status": "passing",
"Notes":"", "Notes": "",
"Output": "", "Output": "",
"ServiceID":"redis", "ServiceID": "redis",
"ServiceName":"redis" "ServiceName": "redis"
} }
] ]
@ -656,14 +667,14 @@ It returns a JSON body like this:
[ [
{ {
"Node":"foobar", "Node": "foobar",
"CheckID":"service:redis", "CheckID": "service:redis",
"Name":"Service 'redis' check", "Name": "Service 'redis' check",
"Status":"passing", "Status": "passing",
"Notes":"", "Notes": "",
"Output": "", "Output": "",
"ServiceID":"redis", "ServiceID": "redis",
"ServiceName":"redis" "ServiceName": "redis"
} }
] ]
@ -696,35 +707,36 @@ It returns a JSON body like this:
[ [
{ {
"Node":{ "Node": {
"Node":"foobar", "Node": "foobar",
"Address":"10.1.10.12" "Address": "10.1.10.12"
}, },
"Service":{ "Service": {
"ID":"redis", "ID": "redis",
"Service":"redis", "Service": "redis",
"Tags":null, "Tags": null,
"Port":8000 "Port": 8000
}, },
"Checks":[ "Checks": [
{ {
"Node":"foobar", "Node": "foobar",
"CheckID":"service:redis", "CheckID": "service:redis",
"Name":"Service 'redis' check", "Name": "Service 'redis' check",
"Status":"passing", "Status": "passing",
"Notes":"", "Notes": "",
"Output": "", "Output": "",
"ServiceID":"redis", "ServiceID": "redis",
"ServiceName":"redis" "ServiceName": "redis"
},{ },
"Node":"foobar", {
"CheckID":"serfHealth", "Node": "foobar",
"Name":"Serf Health Status", "CheckID": "serfHealth",
"Status":"passing", "Name": "Serf Health Status",
"Notes":"", "Status": "passing",
"Notes": "",
"Output": "", "Output": "",
"ServiceID":"", "ServiceID": "",
"ServiceName":"" "ServiceName": ""
} }
] ]
} }
@ -745,24 +757,24 @@ It returns a JSON body like this:
[ [
{ {
"Node":"foobar", "Node": "foobar",
"CheckID":"serfHealth", "CheckID": "serfHealth",
"Name":"Serf Health Status", "Name": "Serf Health Status",
"Status":"passing", "Status": "passing",
"Notes":"", "Notes": "",
"Output": "", "Output": "",
"ServiceID":"", "ServiceID": "",
"ServiceName":"" "ServiceName": ""
}, },
{ {
"Node":"foobar", "Node": "foobar",
"CheckID":"service:redis", "CheckID": "service:redis",
"Name":"Service 'redis' check", "Name": "Service 'redis' check",
"Status":"passing", "Status": "passing",
"Notes":"", "Notes": "",
"Output": "", "Output": "",
"ServiceID":"redis", "ServiceID": "redis",
"ServiceName":"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: 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"] ["10.1.10.12:8300", "10.1.10.11:8300", "10.1.10.10:8300"]

10
website/source/docs/agent/options.html.markdown
View File

@ -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 * `-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 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 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 guarenteed if multiple 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 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. 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, * `-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 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 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 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 participate in a WAN gossip pool with server nodes in other datacenters. Servers act as gateways
to other datacenters and forward traffic as appropriate. 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`. Must be provided along with the `key_file`.
* `domain` - By default, Consul responds to DNS queries in the "consul." domain. * `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, * `enable_debug` - When set, enables some additional debugging features. Currently,
only used to set the runtime profiling HTTP endpoints. 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 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, will not make use of TLS for outgoing connections. This applies to clients and servers,
as both will make outgoing connections. as both will make outgoing connections.

3
website/source/docs/agent/rpc.html.markdown
View File

@ -169,7 +169,7 @@ we may start getting messages like:
{"Log": "2013/12/03 13:06:53 [INFO] agent: Received event: member-join"} {"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 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 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 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:
... ...
} }
``` ```