Configuring Consul Snapshot Agent with Azure Blob Storage using Service Principal ID and Secret

Avatar
Suyash Kumar
  • Updated

This guide provides a step-by-step configuration to enable HashiCorp Consul's Snapshot Agent to store backup snapshots on Azure Blob Storage, using a Service Principal ID and Secret for authentication. This configuration allows automated, secure, and periodic snapshots of your Consul data, which are stored in a designated Azure Blob Storage container.

 

Prerequisites

  1. Azure Account with permissions to create an application and assign it roles.
  2. Azure CLI installed and configured with appropriate permissions Storage Blob Data Contributor role on the target container for read/write access to Azure Blob Storage.
  3. Consul Enterprise Cluster (v1.20.1 or later) installed and running.

 

Steps

Step 1: Create an Azure Service Principal Using Azure CLI

The Service Principal will be used to authenticate the Consul Snapshot Agent to Azure Blob Storage.

1.1 Register an Application

Create an Azure AD application:

az ad app create --display-name "<YourAppName>"

This command registers a new application in Azure Active Directory. Note the appId (Application (client) ID) in the output, which will be required later.

1.2 Create a Service Principal and Generate a Client Secret

az ad sp create-for-rbac --name "<YourAppName>" --role Contributor --scopes "/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.Storage/storageAccounts/<storage-account-name>"

Replace placeholders with your actual values:

  • <YourAppName>: Name of your application.
  • <subscription-id>: Azure subscription ID.
  • <resource-group>: Resource group of your storage account.
  • <storage-account-name>: Your storage account name.

This command outputs:

  • appId: Application (client) ID
  • password: Client Secret
  • tenant: Tenant ID

Note: Record the appId, password, and tenant for use in the snapshot agent configuration.

1.3 Assign Storage Role Permissions

To enable access to your Blob Storage, assign the Storage Blob Data Contributor role to the Service Principal:

az role assignment create --assignee "<appId>" --role "Storage Blob Data Contributor" --scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.Storage/storageAccounts/<storage-account-name>"

Replace <appId> with the Application (client) ID and update other placeholders.

 

Step 2: Configure Consul Snapshot Agent with Service Principal Credentials

Now, configure the snapshot.json file to enable the Consul Snapshot Agent to use Azure Blob Storage as the backup destination. This configuration includes specifying the service_principal_id, service_principal_secret, and tenant_id in the backup destinations.

Below is an example snapshot.json configuration file:

{
  "snapshot_agent": {
    "http_addr": "127.0.0.1:8500",
    "token": "",
    "datacenter": "",
    "ca_file": "",
    "ca_path": "",
    "cert_file": "",
    "key_file": "",
    "license_path": "",
    "tls_server_name": "",
    "login": {
      "auth_method": "",
      "bearer_token": "",
      "bearer_token_file": "",
      "meta": {}
    },
    "log": {
      "level": "TRACE",
      "enable_syslog": false,
      "syslog_facility": "LOCAL0"
    },
    "snapshot": {
      "interval": "1h",
      "retain": 30,
      "stale": false,
      "service": "consul-snapshot",
      "deregister_after": "72h",
      "lock_key": "consul-snapshot/lock",
      "max_failures": 3,
      "local_scratch_path": ""
    },
    "backup_destinations": {
      "azure_blob_storage": [
        {
          "account_name": "********************",
          "service_principal_id": "********************",
          "service_principal_secret": "********************",
          "container_name": "********************",
          "environment": "********************",
          "tenant_id": "********************"
        }
      ]
    }
  }
}

Key Parameters

  • account_name: The Azure Storage account name where the snapshots will be stored.
  • service_principal_id: The Application (client) ID obtained when creating the Service Principal.
  • service_principal_secret: The Client Secret generated during Service Principal creation.
  • container_name: The container in Azure Blob Storage to store the Consul snapshots.
  • environment: Set to AzureCloud (for the public Azure environment).
  • tenant_id: The Tenant ID for your Azure account.

 

Step 3: Start Consul Snapshot agent and Validate

  1. Start the Consul Snapshot Agent: To load the new configuration.

  2. Monitor Logs: Check the Consul Snapshot Agent logs for any authentication or connectivity errors with Azure Blob Storage.

  3. Verifying Snapshot Functionality: Upon starting the Consul Snapshot Agent, the following log sample will confirm a successful connection and operation:

# consul snapshot agent -config-file=/path/to/snapshot.json
==> Consul snapshot agent running!
             Version: 1.20.1+ent
          Datacenter: "dc1"
            Interval: "1h0m0s"
              Retain: 30
               Stale: false
       Local Scratch: /tmp
                Mode: daemon
             Service: "consul-snapshot"
    Deregister After: "72h0m0s"
            Lock Key: "consul-snapshot/lock"
        Max Failures: 3
    Snapshot Storage: Azure Blob Storage -> Environment: "AzureCloud" Account Name: "consulsnapshotsc" Container Name: "snapshots"

==> Log data will now stream in as it occurs:
    2024-11-12T14:30:29.006Z [INFO]  snapshot: Waiting to obtain leadership...
    2024-11-12T14:30:29.010Z [INFO]  snapshot: Obtained leadership
    2024-11-12T14:30:29.013Z [DEBUG] snapshot: Taking a snapshot...
    2024-11-12T14:30:30.857Z [INFO]  azure: Upload of file to Azure Blob Storage successful: filename=consul-1731421829031868653.snap
    2024-11-12T14:30:30.857Z [INFO]  snapshot: Saved snapshot: id=1731421829031868653
    2024-11-12T14:30:31.049Z [DEBUG] snapshot: Rotated snapshots: number_deleted=0

 

Troubleshooting

  1. Unauthorized Client Errors: If you see an error such as unauthorized_client, verify that the service_principal_id, service_principal_secret, and tenant_id are correct and that the Service Principal has the necessary Storage Blob Data Contributor role.

  2. Role Assignment Issues: Ensure the Service Principal has permissions at the correct scope (specific storage account, resource group, or subscription level).

  3. Network Access: Ensure your network security settings (NSG, firewall, etc.) allow outbound traffic from the Consul Snapshot Agent to Azure Blob Storage.

By following these steps, you can configure Consul Snapshot Agent to securely back up data to Azure Blob Storage using Service Principal credentials. This setup ensures that snapshots are securely stored in the cloud for reliable recovery in disaster scenarios.

 

Conclusion

Configuring the Consul Snapshot Agent with Azure Blob Storage using a Service Principal ID and Secret provides a secure and automated solution for backing up and storing Consul data. By following the steps to create an Azure Service Principal, assign the necessary permissions, and configure the snapshot agent, users can ensure that their Consul snapshots are safely stored in a scalable, resilient cloud environment. This setup not only strengthens data recovery strategies but also enables streamlined, reliable access to backups whenever needed. Regular monitoring of the Consul Snapshot Agent and periodic verification of backup storage are recommended to maintain backup integrity and minimize recovery time in case of a disaster.

 

Reference

Consul Snapshot Agent

Register a Microsoft Entra app and create a service principal

Azure Command-Line Interface (CLI) documentation

Articles in this section

Related articles