Vaultx.Sys.Namespaces (Vaultx v0.7.0)

HashiCorp Vault namespaces operations.

This module provides namespace management capabilities for Vault Enterprise, allowing you to create, read, update, delete, and manage namespaces for multi-tenant Vault deployments.

Namespace Features

Core Operations

List Namespaces: Enumerate all available namespaces
Create Namespace: Create new namespaces with metadata
Read Namespace: Get detailed namespace information
Update Namespace: Modify namespace metadata
Delete Namespace: Remove namespaces and their contents

Advanced Operations

Lock Namespace: Lock namespace API access
Unlock Namespace: Restore namespace API access
Patch Namespace: Partial updates to namespace metadata
Custom Metadata: Arbitrary key-value metadata support

Important Notes

Enterprise Feature

Namespaces are only available in Vault Enterprise
Requires appropriate Vault Enterprise license
Not available in Vault Community Edition

Authentication Required

All namespace operations require valid authentication
Appropriate permissions needed for namespace management
Root namespace access may be required for some operations

Destructive Operations

Deleting a namespace removes all contained secrets and policies
Namespace deletion is irreversible
Consider backup and recovery procedures

API Compliance

Fully implements HashiCorp Vault Namespaces API:

Usage Examples

List Namespaces

{:ok, namespaces} = Vaultx.Sys.Namespaces.list()

Enum.each(namespaces.keys, fn namespace ->
  IO.puts("Namespace: #{namespace}")
end)

Create Namespace

{:ok, _} = Vaultx.Sys.Namespaces.create("production", %{
  "environment" => "prod",
  "team" => "platform"
})

Read Namespace Information

{:ok, info} = Vaultx.Sys.Namespaces.read("production")
IO.puts("Namespace ID: #{info.id}")
IO.puts("Path: #{info.path}")

Update Namespace Metadata

{:ok, _} = Vaultx.Sys.Namespaces.update("production", %{
  "environment" => "production",
  "team" => "platform",
  "owner" => "ops-team"
})

Delete Namespace

{:ok, _} = Vaultx.Sys.Namespaces.delete("staging")

Namespace Information

Namespace objects contain:

id: Unique namespace identifier
path: Namespace path (with trailing slash)
custom_metadata: User-defined metadata map

Use Cases

Multi-Tenancy

Isolate different teams or applications
Provide tenant-specific secret management
Implement organizational boundaries
Support compliance requirements

Environment Separation

Separate development, staging, and production
Isolate different deployment environments
Implement environment-specific policies
Control cross-environment access

Organizational Structure

Map namespaces to business units
Implement departmental boundaries
Support hierarchical organizations
Enable decentralized management

Security and Compliance

Implement security boundaries
Support regulatory compliance
Enable audit trail separation
Control data residency requirements

Summary

Types

namespace_info()

Namespace information.

namespace_list()

Namespace list response.

Functions

create(path, custom_metadata \\ %{}, opts \\ [])

Create a new namespace.

delete(path, opts \\ [])

Delete a namespace.

exists?(path, opts \\ [])

Check if a namespace exists.

list(opts \\ [])

List all namespaces.

list_names(opts \\ [])

Get a list of namespace names only.

read(path, opts \\ [])

Read namespace information.

update(path, custom_metadata, opts \\ [])

Update namespace metadata.

Types

namespace_info()

@type namespace_info() :: %{id: String.t(), path: String.t(), custom_metadata: map()}

Namespace information.

namespace_list()

@type namespace_list() :: %{keys: [String.t()], key_info: map()}

Namespace list response.

Functions

create(path, custom_metadata \\ %{}, opts \\ [])

@spec create(String.t(), map(), Vaultx.Types.options()) ::
  {:ok, Vaultx.Types.response()} | {:error, Vaultx.Base.Error.t()}

Create a new namespace.

This endpoint creates a namespace at the given path with optional custom metadata.

Parameters

path - The namespace path to create
custom_metadata - Optional custom metadata map (default: %{})
opts - Request options (optional)

Returns

Returns {:ok, response} on successful creation, or {:error, Error.t()} on failure.

Examples

# Create simple namespace
{:ok, _} = Vaultx.Sys.Namespaces.create("development")

# Create with metadata
{:ok, _} = Vaultx.Sys.Namespaces.create("production", %{
  "environment" => "prod",
  "team" => "platform",
  "contact" => "ops@company.com"
})

delete(path, opts \\ [])

@spec delete(String.t(), Vaultx.Types.options()) ::
  {:ok, Vaultx.Types.response()} | {:error, Vaultx.Base.Error.t()}

Delete a namespace.

This endpoint deletes a namespace at the specified path. This operation is destructive and will remove all secrets, policies, and other data within the namespace.

Parameters

path - The namespace path to delete
opts - Request options (optional)

Returns

Returns {:ok, response} on successful deletion, or {:error, Error.t()} on failure.

Examples

{:ok, _} = Vaultx.Sys.Namespaces.delete("old-project")

Warning

This operation is destructive and irreversible. All data within the namespace will be permanently deleted.

exists?(path, opts \\ [])

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

Check if a namespace exists.

This is a convenience function that checks if a namespace exists by attempting to read its information.

Parameters

path - The namespace path to check
opts - Request options (optional)

Returns

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

Examples

case Vaultx.Sys.Namespaces.exists?("production") do
  {:ok, true} -> IO.puts("Namespace exists")
  {:ok, false} -> IO.puts("Namespace does not exist")
  {:error, error} -> IO.puts("Error: #{error.message}")
end

list(opts \\ [])

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

List all namespaces.

This endpoint lists all the namespaces available to the current token.

Parameters

opts - Request options (optional)

Returns

Returns {:ok, namespace_list()} with namespace information, or {:error, Error.t()} on failure.

Examples

{:ok, namespaces} = Vaultx.Sys.Namespaces.list()

IO.puts("Available namespaces:")
Enum.each(namespaces.keys, fn namespace ->
  info = namespaces.key_info[namespace]
  IO.puts("  #{namespace} (ID: #{info["id"]})")
end)

list_names(opts \\ [])

@spec list_names(Vaultx.Types.options()) ::
  {:ok, [String.t()]} | {:error, Vaultx.Base.Error.t()}

Get a list of namespace names only.

This is a convenience function that returns just the namespace names without additional metadata.

Parameters

opts - Request options (optional)

Returns

Returns {:ok, [String.t()]} with namespace names, or {:error, Error.t()} on failure.

Examples

{:ok, namespace_names} = Vaultx.Sys.Namespaces.list_names()
IO.puts("Namespaces: #{Enum.join(namespace_names, ", ")}")

read(path, opts \\ [])

@spec read(String.t(), Vaultx.Types.options()) ::
  {:ok, namespace_info()} | {:error, Vaultx.Base.Error.t()}

Read namespace information.

This endpoint gets the metadata for the given namespace path.

Parameters

path - The namespace path to read
opts - Request options (optional)

Returns

Returns {:ok, namespace_info()} with namespace information, or {:error, Error.t()} on failure.

Examples

{:ok, info} = Vaultx.Sys.Namespaces.read("production")

IO.puts("Namespace ID: #{info.id}")
IO.puts("Path: #{info.path}")
IO.puts("Metadata: #{inspect(info.custom_metadata)}")

update(path, custom_metadata, opts \\ [])

@spec update(String.t(), map(), Vaultx.Types.options()) ::
  {:ok, Vaultx.Types.response()} | {:error, Vaultx.Base.Error.t()}

Update namespace metadata.

This endpoint updates the custom metadata for an existing namespace.

Parameters

path - The namespace path to update
custom_metadata - New custom metadata map
opts - Request options (optional)

Returns

Returns {:ok, response} on successful update, or {:error, Error.t()} on failure.

Examples

{:ok, _} = Vaultx.Sys.Namespaces.update("production", %{
  "environment" => "production",
  "team" => "platform",
  "updated_at" => DateTime.utc_now() |> DateTime.to_iso8601()
})