HashiCorp Consul operations

v0.2.35

Deep Consul ops — agent self/metrics/host introspection, operator raft + autopilot + reload, catalog (services + nodes + datacenters), health (passing/warning/critical) with force-pass/fail/warn check mutators, KV (get/list/recursive), ACL tokens/policies/roles, Connect mesh (CA roots, intentions), sessions, prepared queries, snapshots (save/inspect/restore), and narrow operator actions (deregister, maintenance, raft remove-peer). Auth via CONSUL_HTTP_ADDR + CONSUL_HTTP_TOKEN env vars.

35 allowed by default 10 need approval by default 2 denied by default

Pack ID

consul

Vendor

emisar

linux

Actions

Required binaries. Install these on the host before relying on the pack — an action that calls a missing one fails at run time.


              consul


              curl

jq

Install

emisar pack install fetches this pack, re-validates it, and verifies its content hash against the --hash below — the exact bytes this page was rendered against, so a tampered copy is rejected — before copying it into the runner's packs dir. The command reloads a running daemon itself; no manual restart.

on the runner host

sudo emisar pack install consul --hash sha256:11b989af50a8c30dcde9ca240854780562e9e7983e494f0e687bbcf5cb93edd9

Setup

Both the consul CLI and the curl-based API actions read the agent address, ACL token, and TLS certificate settings from the standard Consul environment variables on the runner host.

Environment

Set these on the runner host, then add each name to execution.inherit_env so the value reaches the action.

CONSUL_HTTP_ADDR default http://127.0.0.1:8500

Agent HTTP address, including scheme (the curl actions build URLs directly from it).
CONSUL_HTTP_TOKEN

ACL token. Required when ACLs are enabled; its policy gates which actions succeed.
CONSUL_CACERT

Optional path to the CA certificate used to verify the agent's HTTPS certificate.
CONSUL_CLIENT_CERT

Optional path to the client certificate when the agent requires mutual TLS.
CONSUL_CLIENT_KEY

Optional path to the client certificate's private key when the agent requires mutual TLS.

Host access

Run these commands yourself on the runner host. Emisar shows and copies setup recipes; it never runs them.

Read and write Consul snapshot files in a dedicated host backup directory.

consul.snapshot_saveconsul.snapshot_inspectconsul.snapshot_restore

Create the Emisar Consul snapshot directory

Grant access

sudo install -d -o root -g emisar -m 0770 /var/backups/emisar-consul

Verify access

sudo -u emisar test -r /var/backups/emisar-consul
sudo -u emisar test -w /var/backups/emisar-consul

Impact: Every process running as emisar can read, replace, and delete snapshots in this directory. Consul snapshots contain raw KV, ACL, service, and session state.

Notes

Any Consul variable you set must also be allowlisted in the runner's execution.inherit_env — the action env is scrubbed to PATH / LANG / LC_ALL / TERM by default, so an env present on the host but not allowlisted is silently dropped (the action falls back to its local default or fails auth).
On a cluster with ACLs enabled the token must grant the rights the action needs — operator/write for raft_remove_peer and reload, service/node write for the maintenance and deregister mutators, and key/read for the KV reads.
For TLS-enabled agents use an https:// CONSUL_HTTP_ADDR . CONSUL_CACERT , CONSUL_CLIENT_CERT , and CONSUL_CLIENT_KEY apply uniformly to the Consul CLI and raw API actions. Set the client certificate and key together.

Verify it works

Runs consul.members, a low-risk read that confirms the pack can reach its target. Run it on the host once the pack is installed; pack install runs it for you.

on the runner host

sudo emisar pack verify consul

Install and configure a pack walks through the whole sequence on a host.

Actions 47 total

View on GitHub

consul.acl_token_self script low

GET /v1/acl/token/self

Show metadata on the runner's own token — accessor, policies, roles, expiration. The SecretID the API returns is redacted from the output.
View source on GitHub
consul.agent_checks script low

GET /v1/agent/checks

List checks registered with the local agent + their current status.
View source on GitHub
consul.agent_host_info script low

GET /v1/agent/host

Show host info: OS, CPU, memory, filesystem, network from the agent's view.
View source on GitHub
consul.agent_metrics script low

GET /v1/agent/metrics

Show current runtime metrics gauges + counters.
View source on GitHub
consul.agent_self script low

GET /v1/agent/self

Show this agent's effective config, runtime, member, and ACL state.
View source on GitHub
consul.agent_services script low

GET /v1/agent/services

List the services registered with the local agent.
View source on GitHub
consul.autopilot_state script low

GET /v1/operator/autopilot/state

Show the Autopilot view of cluster health: server stabilization, leader, failure tolerance.
View source on GitHub
consul.catalog_datacenters script low

GET /v1/catalog/datacenters

List all WAN-federated datacenters known to this server.
View source on GitHub
consul.catalog_service script low

GET /v1/catalog/service/<name>

List all instances of one service across the cluster.
View source on GitHub
consul.connect_ca_configuration script medium

GET /v1/connect/ca/configuration

Show CA provider configuration (which CA, intermediate cert TTL, etc). Provider secrets the config map may carry — the Vault provider's Token and the built-in provider's PrivateKey — are redacted from the output.
View source on GitHub
consul.connect_ca_roots script low

GET /v1/connect/ca/roots

List currently-trusted root CAs for Connect mesh TLS.
View source on GitHub
consul.deregister_service exec high

consul services deregister

Remove one service registration from this agent; it disappears from discovery immediately and clients stop being routed to that instance.
View source on GitHub
consul.destroy_session script high

PUT /v1/session/destroy/<id>

Destroy one session. Any locks held are released; KV entries with release behavior are unlocked.
View source on GitHub
consul.force_check_fail script high

PUT /v1/agent/check/fail/<check_id>

Force one check into CRITICAL state. Service discovery stops returning it.
View source on GitHub
consul.force_check_pass script high

PUT /v1/agent/check/pass/<check_id>

Force one TTL check into the PASSING state; discovery resumes routing traffic to the service even if it is genuinely unhealthy. The check stays passing until the next TTL expires.
View source on GitHub
consul.force_check_warn script high

PUT /v1/agent/check/warn/<check_id>

Force one check into WARNING state; strict (passing-only) discovery stops returning the associated service.
View source on GitHub
consul.intentions_list script low

GET /v1/connect/intentions

List all Connect mesh intentions (allow/deny rules between services).
View source on GitHub
consul.intentions_match script low

GET /v1/connect/intentions/match (by destination)

List all intentions whose destination is the named service. Use to answer "what can talk to X?".
View source on GitHub
consul.kv_get exec high

consul kv get <key>

Get the value at one KV key.
View source on GitHub
consul.kv_get_recursive exec high

consul kv get -recurse <prefix>

Get all keys + values under a prefix.
View source on GitHub
consul.kv_list exec low

consul kv get -keys <prefix>

List all KV keys under one prefix.
View source on GitHub
consul.leader script low

GET /v1/status/leader

Show the current Raft leader address for this datacenter. Reads the status endpoint, which is not ACL-gated, so it answers "is there a leader?" even when no CONSUL_HTTP_TOKEN is set.
View source on GitHub
consul.list_acl_policies exec low

consul acl policy list

List all ACL policies.
View source on GitHub
consul.list_acl_roles exec low

consul acl role list

List all ACL roles (groups of policies).
View source on GitHub
consul.list_acl_tokens exec low

consul acl token list

List ACL tokens (descriptions + accessor IDs only, not secrets).
View source on GitHub
consul.list_checks_critical script low

GET /v1/health/state/critical

List every check currently in CRITICAL state across the catalog.
View source on GitHub
consul.list_checks_warning script low

GET /v1/health/state/warning

List every check currently in WARNING state.
View source on GitHub
consul.list_nodes exec low

consul catalog nodes

List all registered nodes.
View source on GitHub
consul.list_services exec low

consul catalog services

List all registered service names.
View source on GitHub
consul.list_sessions script low

GET /v1/session/list

List active sessions cluster-wide: ID, node, TTL, behavior.
View source on GitHub
consul.members exec low

consul members

List all agents in the gossip pool with status, role, version.
View source on GitHub
consul.node_health script low

GET /v1/health/node/<node>

List all checks for one node + their status.
View source on GitHub
consul.node_maintenance exec high

consul maint -enable

Enable maintenance mode on this agent's node. Health checks fail until disabled.
View source on GitHub
consul.node_maintenance_disable exec medium

consul maint -disable

Disable maintenance mode on this agent's node, so its health checks report normally and service discovery routes to it again — the reverse of consul.node_maintenance. Consul persists maintenance mode across an agent restart, so this is the only thing that clears it.
View source on GitHub
consul.node_services script low

GET /v1/catalog/node-services/<node>

List all services registered against one node.
View source on GitHub
consul.prepared_queries_list script low

GET /v1/query

List all defined prepared queries (named service-discovery templates with failover).
View source on GitHub
consul.raft_peers exec low

consul operator raft list-peers

List the server peers with voter status, suffix, address.
View source on GitHub
consul.raft_remove_peer exec critical

consul operator raft remove-peer

Remove a server from Raft forcibly. Use ONLY when a server is permanently gone and autopilot hasn't cleaned it up.
View source on GitHub
consul.registration_churn_snapshot script low

Registration churn incident snapshot

Sample the local Consul agent's completed telemetry interval twice, then return a compact JSON incident snapshot with registration, deregistration, and ACL-blocked mutation deltas plus bounded local services, failing checks, and services explicitly registered to loopback. The metrics endpoint reports completed ten-second aggregation intervals, so this is a focused diagnostic sample rather than an audit log. Deltas are null when both reads observe the same completed interval.
View source on GitHub
consul.reload exec high

consul reload

Reload the local agent's config (re-reads HCL files). Some settings can't be reloaded — see consul docs.
View source on GitHub
consul.service_health script low

Health of a service's instances

Show per-node health for one service.
View source on GitHub
consul.service_maintenance exec high

consul maint -enable -service <svc>

Put one local-agent service into maintenance mode. Its checks report critical until disabled.
View source on GitHub
consul.service_maintenance_disable exec medium

consul maint -disable -service <svc>

Disable maintenance mode for one local-agent service, so its checks report normally and discovery routes to it again — the reverse of consul.service_maintenance. Consul persists maintenance mode across an agent restart, so this is the only thing that clears it.
View source on GitHub
consul.service_passing_only script low

GET /v1/health/service/<name>?passing

List only healthy (all-passing) instances of one service. What service discovery would return.
View source on GitHub
consul.snapshot_inspect exec low

consul snapshot inspect <path>

Show a summary of one snapshot file — size, index, KV count, ACL count.
View source on GitHub
consul.snapshot_restore exec critical

consul snapshot restore <path>

Restore cluster state from a snapshot. ALL existing state (KV, services, sessions, intentions, ACL) is REPLACED. Cluster briefly unavailable during restore.
View source on GitHub
consul.snapshot_save exec medium

consul snapshot save <path>

Write a Raft snapshot to a local file. Use before risky operations + as a backup.
View source on GitHub

← Back to registry

Pack reference Publish your own