Vaultx.Secrets.Consul (Vaultx v0.7.0)

View Source

Unified Consul secrets engine interface for HashiCorp Vault.

This module provides a comprehensive, enterprise-grade interface for the Consul secrets engine, offering dynamic credential management, configuration operations, and role management. It supports all Consul credential types with advanced security features and compliance capabilities.

Enterprise Consul Credential Management

  • Dynamic Credential Generation: Consul ACL tokens with policies, roles, and service identities
  • Configuration Management: Root credentials, access settings, and connection parameters
  • Role Management: Dynamic role configuration with policy enforcement
  • Multi-Version Support: Compatible with Consul 1.4+ through latest versions
  • Security Compliance: Audit logging, least privilege, and policy validation

Supported Credential Types

Modern Consul (1.5+)

  • Consul Policies: Named policies for fine-grained access control
  • Consul Roles: Pre-defined role-based access patterns
  • Service Identities: Service-specific access tokens
  • Node Identities: Node-specific access tokens (1.8+)
  • Namespace Support: Multi-tenant Consul deployments (1.7+)
  • Admin Partitions: Enterprise multi-partition support (1.11+)

Legacy Consul (1.4 and below)

  • Base64-encoded ACL policies
  • Management and client token types

Configuration Examples

# Configure root Consul credentials
config = %{
  address: "127.0.0.1:8500",
  scheme: "https",
  token: "management-token-here",
  ca_cert: "-----BEGIN CERTIFICATE-----...",
  client_cert: "-----BEGIN CERTIFICATE-----...",
  client_key: "-----BEGIN PRIVATE KEY-----..."
}
{:ok, _} = Consul.configure_access(config)

# Create a modern role with policies
role_config = %{
  consul_policies: ["web-policy", "db-read-policy"],
  consul_namespace: "production",
  ttl: "1h",
  max_ttl: "24h"
}
{:ok, _} = Consul.create_role("web-service", role_config)

# Generate credentials
{:ok, creds} = Consul.generate_credentials("web-service")

API Compliance

Fully implements HashiCorp Vault Consul secrets engine:

Summary

Functions

configure_access(config, opts \\ [])

Configure access information for Consul.

create_role(name, config, opts \\ [])

Create or update a Consul role.

delete_role(name, opts \\ [])

Delete a Consul role.

generate_credentials(name, opts \\ [])

Generate credentials for a Consul role.

list_roles(opts \\ [])

List all configured Consul roles.

read_role(name, opts \\ [])

Read a Consul role configuration.

Functions

configure_access(config, opts \\ [])

Configure access information for Consul.

Sets up the Consul connection parameters that Vault will use to communicate with Consul and generate tokens. Supports both HTTP and HTTPS connections with optional TLS client certificate authentication.

Parameters

  • config - Access configuration parameters
  • opts - Request options including mount path

Examples

# Basic HTTP configuration
config = %{
  address: "127.0.0.1:8500",
  scheme: "http",
  token: "management-token"
}
{:ok, _} = Consul.configure_access(config)

# HTTPS with client certificates
config = %{
  address: "consul.example.com:8501",
  scheme: "https",
  token: "management-token",
  ca_cert: File.read!("ca.pem"),
  client_cert: File.read!("client.pem"),
  client_key: File.read!("client-key.pem")
}

create_role(name, config, opts \\ [])

Create or update a Consul role.

Configures a role that can be used to generate Consul ACL tokens. The role defines the type of credentials to generate and the associated policies, roles, and constraints.

Parameters

  • name - Role name
  • config - Role configuration
  • opts - Request options

Examples

# Modern Consul with policies (1.4+)
config = %{
  consul_policies: ["web-policy", "db-read-policy"],
  consul_namespace: "production",
  ttl: "1h",
  max_ttl: "24h",
  local: false
}
{:ok, _} = Consul.create_role("web-service", config)

# With service identities (1.5+)
config = %{
  service_identities: [
    "web:dc1,dc2",
    "api:dc1"
  ],
  consul_namespace: "production"
}
{:ok, _} = Consul.create_role("service-role", config)

# With node identities (1.8+)
config = %{
  node_identities: [
    "web-01:dc1",
    "web-02:dc1"
  ],
  partition: "frontend"
}
{:ok, _} = Consul.create_role("node-role", config)

delete_role(name, opts \\ [])

Delete a Consul role.

Examples

:ok = Consul.delete_role("old-role")

generate_credentials(name, opts \\ [])

Generate credentials for a Consul role.

Generates a dynamic Consul ACL token based on the given role definition. The token will have the policies, roles, and identities configured in the role.

Parameters

  • name - Role name to generate credentials for
  • opts - Request options

Returns

  • {:ok, credentials} - Successfully generated credentials
  • {:error, error} - Failed to generate credentials

Examples

{:ok, creds} = Consul.generate_credentials("web-service")
%{
  token: "8f246b77-f3e1-ff88-5b48-8ec93abf3e05"
}

list_roles(opts \\ [])

List all configured Consul roles.

Examples

{:ok, roles} = Consul.list_roles()
["web-service", "api-service", "node-role"]

read_role(name, opts \\ [])

Read a Consul role configuration.

Examples

{:ok, config} = Consul.read_role("web-service")
%{
  consul_policies: ["web-policy", "db-read-policy"],
  consul_namespace: "production",
  ttl: "1h0m0s",
  max_ttl: "24h0m0s",
  local: false
}