Vaultx.Sys.SealStatus (Vaultx v0.7.0)

View Source

HashiCorp Vault seal status operations.

This module provides seal status checking capabilities for Vault, allowing you to retrieve detailed information about the current seal state, configuration, and operational status without requiring authentication.

Seal Status Features

Core Information

  • Seal State: Whether Vault is currently sealed or unsealed
  • Configuration: Threshold and total key shares information
  • Progress: Current unsealing progress when partially unsealed
  • Version Info: Vault version and build information
  • Cluster Info: Cluster name and ID when unsealed

Operational Details

  • Storage Type: Backend storage configuration
  • Seal Type: Shamir, auto-seal, or other seal mechanisms
  • Migration Status: Whether seal migration is in progress
  • Recovery Seal: Recovery seal configuration status
  • Cluster Status: High availability and cluster information

Important Notes

Unauthenticated Endpoint

  • No authentication required to check seal status
  • Safe to call from monitoring and health check systems
  • Does not expose sensitive information

High Availability Information

  • Cluster information only available when unsealed
  • Different nodes may report different status during transitions
  • Use for cluster health monitoring and automation

API Compliance

Fully implements HashiCorp Vault Seal Status API:

Usage Examples

Basic Status Check

{:ok, status} = Vaultx.Sys.SealStatus.get()

if status.sealed do
  IO.puts("Vault is sealed - progress: #{status.progress}/#{status.t}")
else
  IO.puts("Vault is unsealed - cluster: #{status.cluster_name}")
end

Monitoring Integration

case Vaultx.Sys.SealStatus.get() do
  {:ok, status} ->
    if status.sealed do
      # Alert: Vault is sealed
      send_alert("Vault is sealed")
    end
  {:error, _} ->
    # Alert: Cannot reach Vault
    send_alert("Vault unreachable")
end

Wait for Unseal

{:ok, status} = Vaultx.Sys.SealStatus.wait_for_unseal(timeout: 300_000)
IO.puts("Vault is now unsealed!")

Status Information

The seal status response includes:

Always Present

  • sealed: Boolean indicating if Vault is sealed
  • t: Threshold number of keys required to unseal
  • n: Total number of key shares
  • progress: Current number of keys submitted
  • version: Vault version string
  • build_date: Build timestamp
  • storage_type: Storage backend type
  • type: Seal type (shamir, auto, etc.)

When Unsealed

  • cluster_name: Name of the Vault cluster
  • cluster_id: Unique cluster identifier

Additional Fields

  • initialized: Whether Vault has been initialized
  • migration: Whether seal migration is in progress
  • recovery_seal: Recovery seal status
  • removed_from_cluster: Cluster membership status
  • nonce: Current operation nonce

Summary

Types

seal_status()

Seal status information.

Functions

get(opts \\ [])

Get the current seal status of the Vault.

get_unseal_progress(opts \\ [])

Get unsealing progress information.

is_sealed?(opts \\ [])

Check if the Vault is currently sealed.

is_unsealed?(opts \\ [])

Check if the Vault is currently unsealed.

wait_for_unseal(opts \\ [])

Wait for the Vault to become unsealed.

Types

seal_status()

@type seal_status() :: %{
  :sealed => boolean(),
  :t => integer(),
  :n => integer(),
  :progress => integer(),
  :version => String.t(),
  :build_date => String.t(),
  :storage_type => String.t(),
  :type => String.t(),
  :initialized => boolean(),
  :migration => boolean(),
  :recovery_seal => boolean(),
  :removed_from_cluster => boolean(),
  :nonce => String.t(),
  optional(:cluster_name) => String.t(),
  optional(:cluster_id) => String.t()
}

Seal status information.

Functions

get(opts \\ [])

@spec get(Vaultx.Types.options()) ::
  {:ok, seal_status()} | {:error, Vaultx.Base.Error.t()}

Get the current seal status of the Vault.

This endpoint returns the seal status of the Vault. This is an unauthenticated endpoint that can be used for monitoring and health checking.

Parameters

  • opts - Request options (optional)

Returns

Returns {:ok, seal_status()} with current seal status, or {:error, Error.t()} on failure.

Examples

{:ok, status} = Vaultx.Sys.SealStatus.get()

IO.puts("Sealed: #{status.sealed}")
IO.puts("Version: #{status.version}")
IO.puts("Storage: #{status.storage_type}")

if status.sealed do
  IO.puts("Progress: #{status.progress}/#{status.t}")
else
  IO.puts("Cluster: #{status.cluster_name}")
end

get_unseal_progress(opts \\ [])

@spec get_unseal_progress(Vaultx.Types.options()) ::
  {:ok, %{current: integer(), required: integer(), remaining: integer()}}
  | {:error, Vaultx.Base.Error.t()}

Get unsealing progress information.

This function returns detailed progress information for the current unsealing process.

Parameters

  • opts - Request options (optional)

Returns

Returns {:ok, progress_info} with progress details, or {:error, Error.t()} on failure.

Examples

{:ok, progress} = Vaultx.Sys.SealStatus.get_unseal_progress()
IO.puts("Progress: #{progress.current}/#{progress.required}")
IO.puts("Remaining: #{progress.remaining}")

is_sealed?(opts \\ [])

@spec is_sealed?(Vaultx.Types.options()) ::
  {:ok, boolean()} | {:error, Vaultx.Base.Error.t()}

Check if the Vault is currently sealed.

This is a convenience function that returns a simple boolean indicating the seal state.

Parameters

  • opts - Request options (optional)

Returns

Returns {:ok, boolean()} where true means sealed, or {:error, Error.t()} on failure.

Examples

case Vaultx.Sys.SealStatus.is_sealed?() do
  {:ok, true} -> IO.puts("Vault is sealed")
  {:ok, false} -> IO.puts("Vault is unsealed")
  {:error, error} -> IO.puts("Error: #{error.message}")
end

is_unsealed?(opts \\ [])

@spec is_unsealed?(Vaultx.Types.options()) ::
  {:ok, boolean()} | {:error, Vaultx.Base.Error.t()}

Check if the Vault is currently unsealed.

This is a convenience function that returns a simple boolean indicating if the Vault is ready for operations.

Parameters

  • opts - Request options (optional)

Returns

Returns {:ok, boolean()} where true means unsealed and ready, or {:error, Error.t()} on failure.

Examples

case Vaultx.Sys.SealStatus.is_unsealed?() do
  {:ok, true} -> IO.puts("Vault is ready")
  {:ok, false} -> IO.puts("Vault is sealed")
  {:error, error} -> IO.puts("Error: #{error.message}")
end

wait_for_unseal(opts \\ [])

@spec wait_for_unseal(Vaultx.Types.options()) ::
  {:ok, seal_status()} | {:error, Vaultx.Base.Error.t()}

Wait for the Vault to become unsealed.

This function polls the seal status until the Vault becomes unsealed or the timeout is reached.

Parameters

  • opts - Options for the wait operation
    • :timeout - Maximum time to wait in milliseconds (default: 60_000)
    • :interval - Polling interval in milliseconds (default: 1_000)
    • Other HTTP request options

Returns

Returns {:ok, seal_status()} when Vault becomes unsealed, or {:error, Error.t()} on timeout or failure.

Examples

# Wait up to 5 minutes for unseal
{:ok, status} = Vaultx.Sys.SealStatus.wait_for_unseal(timeout: 300_000)
IO.puts("Vault is now unsealed!")

# Custom polling interval
{:ok, status} = Vaultx.Sys.SealStatus.wait_for_unseal(
  timeout: 120_000,
  interval: 2_000
)