Vaultx.Secrets.Nomad.Behaviour behaviour (Vaultx v0.7.0)

View Source

Behaviour definition for HashiCorp Vault Nomad secrets engine operations.

This behaviour defines the interface that Nomad secrets engine implementations must provide, ensuring consistency and type safety across different implementations.

Core Operations

The Nomad secrets engine supports the following operations:

Configuration Operations

  • configure_access/2 - Configure Nomad connection parameters
  • read_access_config/1 - Read Nomad access configuration
  • configure_lease/2 - Configure lease settings for generated tokens
  • read_lease_config/1 - Read lease configuration
  • delete_lease_config/1 - Delete lease configuration

Role Management Operations

  • create_role/3 - Create or update a Nomad role
  • read_role/2 - Read a Nomad role configuration
  • list_roles/1 - List all configured roles
  • delete_role/2 - Delete a Nomad role

Credential Operations

  • generate_credentials/2 - Generate dynamic Nomad tokens

API Compliance

This behaviour ensures compliance with:

Summary

Types

access_config()

Nomad access configuration parameters.

configure_result()

Result of a configuration operation.

create_role_result()

Result of a role creation operation.

credentials()

Generated Nomad credentials.

delete_role_result()

Result of a role delete operation.

generate_credentials_result()

Result of a credential generation operation.

lease_config()

Nomad lease configuration parameters.

list_roles_result()

Result of a role list operation.

operation_opts()

Options for Nomad secrets engine operations.

read_config_result()

Result of a read configuration operation.

read_role_result()

Result of a role read operation.

role_config()

Nomad role configuration parameters.

role_name()

Nomad role name. Must be a non-empty string with valid characters.

Callbacks

configure_access(access_config, operation_opts)

Configure access information for Nomad.

configure_lease(lease_config, operation_opts)

Configure lease settings for generated tokens.

create_role(role_name, role_config, operation_opts)

Create or update a Nomad role.

delete_lease_config(operation_opts)

Delete lease configuration.

delete_role(role_name, operation_opts)

Delete a Nomad role.

generate_credentials(role_name, operation_opts)

Generate credentials for a Nomad role.

list_roles(operation_opts)

List all configured Nomad roles.

read_access_config(operation_opts)

Read access configuration for Nomad.

read_lease_config(operation_opts)

Read lease configuration.

read_role(role_name, operation_opts)

Read a Nomad role configuration.

Types

access_config()

@type access_config() :: %{
  :address => String.t(),
  optional(:token) => String.t(),
  optional(:max_token_name_length) => non_neg_integer(),
  optional(:ca_cert) => String.t(),
  optional(:client_cert) => String.t(),
  optional(:client_key) => String.t()
}

Nomad access configuration parameters.

configure_result()

@type configure_result() :: :ok | {:error, Vaultx.Base.Error.t()}

Result of a configuration operation.

create_role_result()

@type create_role_result() :: :ok | {:error, Vaultx.Base.Error.t()}

Result of a role creation operation.

credentials()

@type credentials() :: %{accessor_id: String.t(), secret_id: String.t()}

Generated Nomad credentials.

delete_role_result()

@type delete_role_result() :: :ok | {:error, Vaultx.Base.Error.t()}

Result of a role delete operation.

generate_credentials_result()

@type generate_credentials_result() ::
  {:ok, credentials()} | {:error, Vaultx.Base.Error.t()}

Result of a credential generation operation.

lease_config()

@type lease_config() :: %{
  optional(:ttl) => String.t(),
  optional(:max_ttl) => String.t()
}

Nomad lease configuration parameters.

list_roles_result()

@type list_roles_result() :: {:ok, [String.t()]} | {:error, Vaultx.Base.Error.t()}

Result of a role list operation.

operation_opts()

@type operation_opts() :: [
  mount_path: String.t(),
  timeout: pos_integer(),
  retry_attempts: non_neg_integer()
]

Options for Nomad secrets engine operations.

read_config_result()

@type read_config_result() :: {:ok, map()} | {:error, Vaultx.Base.Error.t()}

Result of a read configuration operation.

read_role_result()

@type read_role_result() :: {:ok, role_config()} | {:error, Vaultx.Base.Error.t()}

Result of a role read operation.

role_config()

@type role_config() :: %{
  optional(:policies) => String.t(),
  optional(:global) => boolean(),
  optional(:type) => String.t()
}

Nomad role configuration parameters.

role_name()

@type role_name() :: String.t()

Nomad role name. Must be a non-empty string with valid characters.

Callbacks

configure_access(access_config, operation_opts)

@callback configure_access(access_config(), operation_opts()) :: configure_result()

Configure access information for Nomad.

Sets up the connection parameters that Vault will use to communicate with Nomad and generate tokens.

Parameters

  • config - Access configuration parameters
  • opts - Operation options

Returns

  • :ok - Successfully configured access
  • {:error, error} - Failed to configure access

Examples

config = %{
  address: "http://127.0.0.1:4646",
  token: "management-token"
}
:ok = MyNomad.configure_access(config, [])

configure_lease(lease_config, operation_opts)

@callback configure_lease(lease_config(), operation_opts()) :: configure_result()

Configure lease settings for generated tokens.

Parameters

  • config - Lease configuration parameters
  • opts - Operation options

Returns

  • :ok - Successfully configured lease
  • {:error, error} - Failed to configure lease

Examples

config = %{
  ttl: "1h",
  max_ttl: "24h"
}
:ok = MyNomad.configure_lease(config, [])

create_role(role_name, role_config, operation_opts)

@callback create_role(role_name(), role_config(), operation_opts()) ::
  create_role_result()

Create or update a Nomad role.

Configures a role that can be used to generate Nomad tokens. The role defines the policies and type of tokens that will be generated.

Parameters

  • name - Role name
  • config - Role configuration parameters
  • opts - Operation options

Returns

  • :ok - Successfully created/updated role
  • {:error, error} - Failed to create/update role

Examples

config = %{
  policies: "readonly",
  type: "client"
}
:ok = MyNomad.create_role("monitoring", config, [])

delete_lease_config(operation_opts)

@callback delete_lease_config(operation_opts()) :: configure_result()

Delete lease configuration.

Parameters

  • opts - Operation options

Returns

  • :ok - Successfully deleted lease configuration
  • {:error, error} - Failed to delete lease configuration

Examples

:ok = MyNomad.delete_lease_config([])

delete_role(role_name, operation_opts)

@callback delete_role(role_name(), operation_opts()) :: delete_role_result()

Delete a Nomad role.

Parameters

  • name - Role name to delete
  • opts - Operation options

Returns

  • :ok - Successfully deleted role
  • {:error, error} - Failed to delete role

Examples

:ok = MyNomad.delete_role("old-role", [])

generate_credentials(role_name, operation_opts)

@callback generate_credentials(role_name(), operation_opts()) ::
  generate_credentials_result()

Generate credentials for a Nomad role.

Generates a dynamic Nomad token based on the given role definition.

Parameters

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

Returns

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

Examples

{:ok, creds} = MyNomad.generate_credentials("monitoring", [])

list_roles(operation_opts)

@callback list_roles(operation_opts()) :: list_roles_result()

List all configured Nomad roles.

Parameters

  • opts - Operation options

Returns

  • {:ok, roles} - Successfully listed roles
  • {:error, error} - Failed to list roles

Examples

{:ok, roles} = MyNomad.list_roles([])

read_access_config(operation_opts)

@callback read_access_config(operation_opts()) :: read_config_result()

Read access configuration for Nomad.

Parameters

  • opts - Operation options

Returns

  • {:ok, config} - Successfully read access configuration
  • {:error, error} - Failed to read access configuration

Examples

{:ok, config} = MyNomad.read_access_config([])

read_lease_config(operation_opts)

@callback read_lease_config(operation_opts()) :: read_config_result()

Read lease configuration.

Parameters

  • opts - Operation options

Returns

  • {:ok, config} - Successfully read lease configuration
  • {:error, error} - Failed to read lease configuration

Examples

{:ok, config} = MyNomad.read_lease_config([])

read_role(role_name, operation_opts)

@callback read_role(role_name(), operation_opts()) :: read_role_result()

Read a Nomad role configuration.

Parameters

  • name - Role name to read
  • opts - Operation options

Returns

  • {:ok, config} - Successfully read role configuration
  • {:error, error} - Failed to read role

Examples

{:ok, config} = MyNomad.read_role("monitoring", [])