The information contained in this article has been verified as up-to-date on the date of the original publication of the article.  HashiCorp endeavors to keep this information up-to-date and correct, but it makes no representations or warranties of any kind, express or implied, about the ongoing completeness, accuracy, reliability, or suitability of the information provided.

All information contained in this article is for general information purposes only.  Any reliance you place on such information as it applies to your use of your HashiCorp product is therefore strictly at your own risk.

Introduction

Starting in Consul v1.19, PR #20824 introduced a new command to the Consul binary for enhancing the inspection of Raft snapshot files. The snapshot file itself is encoded in a non-readable human format and is useless unless restoring the file and inspecting the state of Consul manually post-restoration.

The consul snapshot decode command works by outputting a stream of line delimited JSON objects that users can process using tools like jq to parse for relevant data.

Prerequisites

• Consul v1.19 or higher
• jq installed
• backup.snapsnapshot file from consul snapshot save or consul snapshot agent

Consul Snapshot Decode

Output Format

Reading in the snapshot backup file produces JSON objects in the below form:

{
  "Type": "<type/struct_name>",
  "Data": {"<JSON Formatted Data>"}
}

Type: String formatted struct request type from the Consul source-code structs package.

Data: JSON Encoded data that varies depending on the struct request type associated.

Decoded Types/Structs

Determining what data is available within the Snapshot backup file starts with understanding the underlying Struct structure map that the command stream returns to the user. To begin inspection, determine the backup file's available data types.

Retrievingbackup.snap Data Types:

$ consul snapshot decode backup.snap | jq -r .Type | uniq

Data
SnapshotHeader
ServiceVirtualIP
FreeVirtualIP
Register
CoordinateBatchUpdate
KVS
Autopilot
ConnectCA
ConnectCAProviderState
ConnectCAConfig
ConfigEntry
ConfigEntry
FederationState
SystemMetadata
Index
Peering
PeeringTrustBundle
PeeringSecret
ChunkingState

Parsing by Type

Each JSON payload returned from the Snapshot backup file stream results in custom data structures that vary based on the type and can help with understanding the state of the objects as seen by Consul during the snapshot backup capture. 

Consul Enterprise Namespaces

# Example: Reading snapshot captured state for Enterprise Namespaces

$ consul snapshot decode backup.snap | jq -r 'select(.Type=="Namespace")'

{
  "Data": {
    "Name": "consul-support-namespace-1",
    "Description": "Test namespace consul-support-namespace-1",
    "CreateIndex": 102,
    "ModifyIndex": 102
  },
  "Type": "Namespace"
}

Consul Configuration Entries

# Example: Reading snapshot capture state for Consul configuration entries

$ consul snapshot decode backup.snap | jq -r 'select(.Type=="ConfigEntry").Data'

{
  "Data": {
    "Op": "",
    "Datacenter": "",
    "Entry": {
      "Kind": "service-intentions",
      "Name": "*",
      "Sources": [
        {
          "Name": "*",
          "Action": "deny",
          "Precedence": 5,
          "LegacyID": "9ba0b45e-1825-be80-6d0d-419bd1c41d6a",
          "Type": "consul",
          "LegacyCreateTime": "2024-04-22T16:03:57.669012Z",
          "LegacyUpdateTime": "2024-04-22T16:03:57.669012Z",
          "Partition": "default",
          "Namespace": "default"
        }
      ],
      "Partition": "default",
      "Namespace": "default",
      "Hash": 12825469602101905988,
      "CreateIndex": 34,
      "ModifyIndex": 34
    },
    "Token": ""
  },
  "Type": "ConfigEntry"
}