VaultX

Hex.pmDocumentationWikiLicenseBuild Status

A modern, high-performance Elixir client for HashiCorp Vault designed for production use.

Why VaultX?

Quick Start

1. Installation

Add to your mix.exs:

def deps do
  [
    {:vaultx, "~> 0.7"}
  ]
end

2. Configuration

Set environment variables:

export VAULTX_URL="https://vault.example.com:8200"
export VAULTX_TOKEN="hvs.xxxxx"

3. Basic Usage

# Read secrets (with intelligent caching)
{:ok, %{data: data}} = Vaultx.Secrets.KV.V2.read("myapp/config")

# Write secrets
{:ok, result} = Vaultx.Secrets.KV.V2.write("myapp/config", %{"key" => "value"})

# Generate dynamic database credentials
{:ok, creds} = Vaultx.Secrets.Database.generate_credentials("readonly-role")
# %{username: "v-root-readonly-abc123", password: "secure-password"}

# System operations
{:ok, health} = Vaultx.Sys.Health.check()
{:ok, seal} = Vaultx.Sys.SealStatus.get()

Core Features

Secrets Management

Authentication Methods

System Operations

Performance & Reliability

Architecture

VaultX follows modern Elixir conventions:

Configuration

Environment Variables

# Core Settings
export VAULTX_URL="https://vault.example.com:8200"
export VAULTX_TOKEN="hvs.xxxxx"
export VAULTX_NAMESPACE="my-namespace"  # Enterprise

# Network & Performance
export VAULTX_TIMEOUT="30000"
export VAULTX_RETRY_ATTEMPTS="3"
export VAULTX_POOL_SIZE="10"

# Security
export VAULTX_SSL_VERIFY="true"
export VAULTX_CACERT="/path/to/ca.pem"
export VAULTX_CLIENT_CERT="/path/to/client.pem"  # mTLS
export VAULTX_CLIENT_KEY="/path/to/client-key.pem"

# Features
export VAULTX_CACHE_ENABLED="true"
export VAULTX_TELEMETRY_ENABLED="true"
export VAULTX_AUDIT_ENABLED="true"

Application Configuration

# config/config.exs
config :vaultx,
  url: "https://vault.example.com:8200",
  timeout: 30_000,
  retry_attempts: 3,
  ssl_verify: true,
  pool_size: 10,
  cache_enabled: true,
  telemetry_enabled: true

For detailed configuration options, see Configuration Guide.

Important Notes

Experimental Features

[!WARNING] The intelligent caching system is currently experimental and may undergo breaking changes in future versions. While functional and tested, the caching API and behavior may change as we gather feedback and optimize performance. Use with caution in production environments.

Limited Docker/Kubernetes Support

[!CAUTION] This project has not been tested or validated for use with Docker or Kubernetes environments. While VaultX may work in containerized deployments, we do not provide official support, testing, or documentation for Docker/Kubernetes integration patterns.

VaultX is designed as a library for BEAM-native deployments, not as a container-first solution. We intentionally focus on Elixir application integration rather than container ecosystems.

Why limited container support:

Recommended patterns:

Examples

Secrets Operations

# KV v2 operations
{:ok, data} = Vaultx.Secrets.KV.V2.read("myapp/database")
{:ok, _} = Vaultx.Secrets.KV.V2.write("myapp/database", %{
  "host" => "db.example.com",
  "password" => "secret123"
})
{:ok, keys} = Vaultx.Secrets.KV.V2.list("myapp/")
{:ok, _} = Vaultx.Secrets.KV.V2.delete("myapp/old-config")

# Dynamic secrets
{:ok, creds} = Vaultx.Secrets.AWS.generate_credentials("deploy-role")
{:ok, cert} = Vaultx.Secrets.PKI.issue_certificate("web-server", %{
  common_name: "api.example.com"
})

System Management

# Health and status
{:ok, health} = Vaultx.Sys.Health.check()
{:ok, seal_status} = Vaultx.Sys.SealStatus.get()

# Lease management
{:ok, lease} = Vaultx.Sys.Leases.lookup("aws/creds/deploy/abcd-1234")
{:ok, renewed} = Vaultx.Sys.Leases.renew("aws/creds/deploy/abcd-1234", 1800)
:ok = Vaultx.Sys.Leases.revoke("aws/creds/deploy/abcd-1234")

# Audit devices
{:ok, devices} = Vaultx.Sys.Audit.list()
{:ok, _} = Vaultx.Sys.Audit.enable("file-audit", "file", %{
  file_path: "/var/log/vault/audit.log"
})

Authentication

# Token authentication
{:ok, token_info} = Vaultx.Auth.Token.lookup_self()
{:ok, renewed} = Vaultx.Auth.Token.renew_self(3600)

# AppRole authentication
{:ok, auth} = Vaultx.Auth.AppRole.login("my-role-id", "my-secret-id")

# JWT authentication
{:ok, auth} = Vaultx.Auth.JWT.login("my-role", jwt_token)

Configuration Analysis

VaultX provides comprehensive configuration analysis and optimization:

# Analyze current configuration
{:ok, analysis} = Vaultx.Config.analyze()
IO.inspect(analysis.performance_score)  # 85.5
IO.inspect(analysis.security_score)     # 92.0
IO.inspect(analysis.suggestions)        # Optimization recommendations

# Validate configuration
:ok = Vaultx.Config.validate()

# Get health status
:healthy = Vaultx.Config.health_status()

[!NOTE] Configuration analysis and optimization features are stable and production-ready. They provide valuable insights into your Vault configuration without affecting runtime behavior.

Deployment Patterns

BEAM-Native (Recommended)

VaultX is designed for BEAM-native deployments using tools like DeployEx:

Container Environments

While VaultX works in containers, we recommend using existing Vault integrations:

Requirements

Contributing

We welcome contributions! Please see CONTRIBUTING.md for details.

License

Copyright (c) 2025 Fleey

Licensed under the MIT License. See LICENSE for details.