Skip to content

Instantly share code, notes, and snippets.

@jreuben11

jreuben11/ConsulQuickRef.md Secret

Last active Dec 14, 2016
Embed
What would you like to do?
Consul QuickRef

HashiCorp Consul https://www.consul.io/ provides an easy to use, multi-region Service Discovery / Health-Check + distributed config keyval store. If you have ever hacked away at coding ZooKeeper to support distributed systems, Consul's Agent based architecture requires an order of magnitude less effort to roll out.

Here's my Consul QuickRef:

CLI options:

  • agent - Runs a Consul agent
    • -dev
    • -server
    • -config-dir=xxx
    • -data-dir=xxx
    • -bind=
    • -bootstrap-expect=<#server-nodes>
    • -name=
    • -atlas-join, -atlas=, atlas-token=xxx
    • -ui #start the ui on http://localhost:8500/ui.
  • config-test - sanity test of config files
  • event - Fire a new event (can be handled by a watch)
    • -http-addr - of the agent
    • -datacenter
    • -name - of the event.
    • -node / service/ tag - regex target filters
    • -token
  • exec - Executes a command on Consul nodes. same options as event +
    • -wait, -wait-repl
  • force-leave Forces a member of the cluster to enter the "left" state
  • info Provides debugging information for operators
  • join Tell Consul agent to join cluster
  • keygen Generates a new encryption key
  • leave Gracefully leaves the Consul cluster and shuts down
  • lock semaphore distributed lock in KV store
    • -n #holders
    • -name
    • -pass-stdin
    • -try, -monitor-retry
  • maint - mark a service provided by a node or the node as a whole as "under maintenance"
    • -enable / disable
    • -reason
    • -service
  • members Lists the members of a Consul cluster:
    • -detailed
    • -status monitor Stream logs from a Consul agent
    • -log-level reload Triggers the agent to reload configuration files version Prints the Consul version watch Watch for changes in Consul
    • -http-addr , datacenter
    • -token
    • -key
    • -name (Event)
    • -passingonly=[true|false] - only passing services
    • -prefix
    • -service - Service to watch
    • -state - Check state to filter on
    • -tag - Service tag to filter on
    • -type - Watch type. Required, one of "key", "keyprefix", "services", "nodes", "service", "checks", or "event".

DNS:

dig @127.0.0.1 -p 9600 <node>.node.consul
[tag.]<service>.service[.datacenter].<domain>
dig @127.0.0.1 -p 9600 <tag>.<service>.service.consul SRV

API:

querystring params

  index=X-Consul-Index  - block until match ?
  wait  - timeout blocking
  consistent / stale - other consistency modes
  near
  passing

curl localhost:8500

/v1/acl/

  • create : Creates a new token with a given policy
  • update : Updates the policy of a token
  • destroy/ : Destroys a given token
  • info/ : Queries the policy of a given token
  • clone/ : Creates a new token by cloning an existing token
  • list : Lists all the active tokens

/v1/agent/

  • checks : Returns the checks the local agent is managing
  • services : Returns the services the local agent is managing
  • members : Returns the members as seen by the local serf agent
  • self : Returns the local node configuration
  • maintenance : Manages node maintenance mode
  • join/ : Triggers the local agent to join a node
  • force-leave/> : Forces removal of a node
  • check/register : Registers a new local check
  • check/deregister/ : Deregisters a local check
  • check/pass/ : Marks a local check as passing
  • check/warn/ : Marks a local check as warning
  • check/fail/ : Marks a local check as critical
  • check/update/ : Updates a local check
  • service/register : Registers a new local service
  • service/deregister/ : Deregisters a local service
  • service/maintenance/ : Manages service maintenance mode

/v1/catalog/

  • register : Registers a new node, service, or check
  • deregister : Deregisters a node, service, or check
  • datacenters : Lists known datacenters
  • nodes : Lists nodes in a given DC
  • services : Lists services in a given DC
  • service/ : Lists the nodes in a given service
  • node/ : Lists the services provided by a node

/v1/event/

  • fire/ : Fires a new user event
  • list : Lists the most recent events an agent has seen.

/v1/health/

  • node/ : Returns the health info of a node
  • checks/ : Returns the checks of a service
  • service/ : Returns the nodes and health info of a service
  • state/ : Returns the checks in a given state

/v1/kv/

  • GET , PUT , DELETE

/v1/coordinate/

  • datacenters : Queries for WAN coordinates of Consul servers
  • nodes : Queries for LAN coordinates of Consul nodes

/v1/query

  • Creates a new prepared query or lists all prepared queries
  • / : Updates, fetches, or deletes a prepared query
  • //execute : Executes a prepared query by its ID or optional name
  • //explain : Provides information about how a prepared query will be executed by its ID or optional name

/v1/session/

  • create : Creates a new session
  • destroy/ : Destroys a given session
  • info/ : Queries a given session
  • node/ : Lists sessions belonging to a node
  • list : Lists all active sessions
  • renew : Renews a TTL-based session

/v1/status/

  • leader : Returns the current Raft leader
  • peers : Returns the current Raft peer set

config:

/etc/consul.d/<service>.json

    {
      "service": {
        "name": "web",
        "tags": ["rails"],
        "port": 80,
        "check": {
          "script": "curl localhost >/dev/null 2>&1",
          "interval": "10s"
        }
      },
      "check": {
        "name": "ping",
        "script": "ping -c1 google.com >/dev/null",
        "interval": "30s"
      }
    }

five different kinds of checks

  • Script + Interval
  • HTTP + Interval
  • TCP + Interval
  • TTL + pass/fail endpoint
  • Docker Exec + Interval

watchers

watch the status of health checks and notify an external system when a check is critical. handler can be any executable - reads JSON input from stdin

types:

  • key - Watch a specific KV pair
  • keyprefix - Watch a prefix in the KV store
  • services - Watch the list of available services
  • nodes - Watch the list of nodes
  • service - Watch the instances of a service
  • checks - Watch the value of health checks
  • event - Watch for custom user events
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.