0
# Vault Hook
1

2
Direct interaction with HashiCorp Vault's Key-Value secret engine for comprehensive secret management operations. The VaultHook provides methods for reading, writing, and managing secrets with full support for both KV version 1 and 2 engines.
3

4
## Capabilities
5

6
### VaultHook Class
7

8
Main hook class for HashiCorp Vault operations with configurable authentication and engine version support.
9

10
```python { .api }
11
class VaultHook(BaseHook):
12
    def __init__(
13
        self,
14
        vault_conn_id: str = "vault_default",
15
        auth_type: str | None = None,
16
        auth_mount_point: str | None = None,
17
        kv_engine_version: int | None = None,
18
        role_id: str | None = None,
19
        region: str | None = None,
20
        kubernetes_role: str | None = None,
21
        kubernetes_jwt_path: str | None = None,
22
        token_path: str | None = None,
23
        gcp_key_path: str | None = None,
24
        gcp_scopes: str | None = None,
25
        azure_tenant_id: str | None = None,
26
        azure_resource: str | None = None,
27
        radius_host: str | None = None,
28
        radius_port: int | None = None,
29
        **kwargs
30
    ):
31
        """
32
        Initialize VaultHook with connection and authentication parameters.
33

34
        Parameters:
35
        - vault_conn_id: Connection ID for Vault configuration
36
        - auth_type: Authentication method ('token', 'approle', 'kubernetes', etc.)
37
        - auth_mount_point: Mount point for authentication method
38
        - kv_engine_version: KV engine version (1 or 2, default: 2)
39
        - role_id: Role ID for AppRole or AWS IAM authentication
40
        - region: AWS region for STS API calls
41
        - kubernetes_role: Role for Kubernetes authentication
42
        - kubernetes_jwt_path: Path to Kubernetes JWT token file
43
        - token_path: Path to authentication token file
44
        - gcp_key_path: Path to GCP service account key file
45
        - gcp_scopes: OAuth2 scopes for GCP authentication
46
        - azure_tenant_id: Azure AD tenant ID
47
        - azure_resource: Azure application URL
48
        - radius_host: RADIUS server host
49
        - radius_secret: RADIUS shared secret
50
        - radius_port: RADIUS server port
51
        """
52
```
53

54
### Connection Management
55

56
Establish and retrieve connections to HashiCorp Vault with automatic authentication handling.
57

58
```python { .api }
59
def get_conn(self) -> hvac.Client:
60
    """
61
    Retrieve authenticated connection to Vault.
62

63
    Returns:
64
    hvac.Client: Authenticated Vault client instance
65
    """
66
```
67

68
### Secret Operations
69

70
Comprehensive secret management operations supporting both read and write operations across KV engine versions.
71

72
```python { .api }
73
def get_secret(self, secret_path: str, secret_version: int | None = None) -> dict | None:
74
    """
75
    Get secret value from the Vault KV engine.
76

77
    Parameters:
78
    - secret_path: Path to the secret in Vault
79
    - secret_version: Specific version to retrieve (KV v2 only)
80

81
    Returns:
82
    dict | None: Secret data as dictionary or None if not found
83
    """
84

85
def create_or_update_secret(
86
    self, 
87
    secret_path: str, 
88
    secret: dict, 
89
    method: str | None = None, 
90
    cas: int | None = None
91
) -> Response:
92
    """
93
    Create or update a secret in Vault.
94

95
    Parameters:
96
    - secret_path: Path where the secret will be stored
97
    - secret: Secret data as dictionary
98
    - method: HTTP method ('POST' for create, 'PUT' for update, KV v1 only)
99
    - cas: Check-And-Set value for version control (KV v2 only)
100

101
    Returns:
102
    Response: HTTP response object from the operation
103
    """
104
```
105

106
### Metadata Operations
107

108
Access secret metadata and version information for KV version 2 engines.
109

110
```python { .api }
111
def get_secret_metadata(self, secret_path: str) -> dict | None:
112
    """
113
    Read secret metadata including all versions (KV v2 only).
114

115
    Parameters:
116
    - secret_path: Path to the secret
117

118
    Returns:
119
    dict | None: Metadata including version information or None if not found
120
    """
121

122
def get_secret_including_metadata(
123
    self, 
124
    secret_path: str, 
125
    secret_version: int | None = None
126
) -> dict | None:
127
    """
128
    Read secret with metadata in a single response (KV v2 only).
129

130
    Parameters:
131
    - secret_path: Path to the secret
132
    - secret_version: Specific version to retrieve
133

134
    Returns:
135
    dict | None: Dictionary with 'data' and 'metadata' keys or None if not found
136
    """
137
```
138

139
### UI Integration
140

141
Methods for integrating with Airflow's web UI connection management.
142

143
```python { .api }
144
@classmethod
145
def get_connection_form_widgets(cls) -> dict[str, Any]:
146
    """
147
    Return connection form widgets for Airflow UI.
148

149
    Returns:
150
    dict[str, Any]: Dictionary of form widget configurations
151
    """
152

153
@classmethod
154
def get_ui_field_behaviour(cls) -> dict[str, Any]:
155
    """
156
    Return UI field behavior configuration.
157

158
    Returns:
159
    dict[str, Any]: UI field behavior settings
160
    """
161

162
def test_connection(self) -> tuple[bool, str]:
163
    """
164
    Test the Vault connection.
165

166
    Returns:
167
    tuple[bool, str]: Success status and descriptive message
168
    """
169
```
170

171
## Types
172

173
```python { .api }
174
# External types used in API signatures
175
import hvac
176
from requests import Response
177
from airflow.providers.hashicorp.version_compat import BaseHook
178
from typing import Any
179
```
180

181
## Usage Examples
182

183
### Basic Secret Retrieval
184

185
```python
186
from airflow.providers.hashicorp.hooks.vault import VaultHook
187

188
# Initialize hook with default connection
189
hook = VaultHook(vault_conn_id='vault_default')
190

191
# Get a secret
192
secret = hook.get_secret('secret/myapp/database')
193
if secret:
194
    db_password = secret.get('password')
195
    db_user = secret.get('username')
196
```
197

198
### Working with KV Version 2
199

200
```python
201
# Get specific version of a secret
202
secret_v2 = hook.get_secret('secret/myapp/api-key', secret_version=2)
203

204
# Get secret with metadata
205
full_data = hook.get_secret_including_metadata('secret/myapp/api-key')
206
secret_data = full_data['data']
207
secret_metadata = full_data['metadata']
208
version = secret_metadata['version']
209

210
# Get just metadata
211
metadata = hook.get_secret_metadata('secret/myapp/api-key')
212
all_versions = metadata['versions']
213
```
214

215
### Creating and Updating Secrets
216

217
```python
218
# Create a new secret
219
new_secret = {
220
    'username': 'admin',
221
    'password': 'secure123',
222
    'api_key': 'abc-123-def'
223
}
224

225
response = hook.create_or_update_secret('secret/myapp/credentials', new_secret)
226

227
# Update with check-and-set (KV v2)
228
updated_secret = {'password': 'newsecure456'}
229
response = hook.create_or_update_secret(
230
    'secret/myapp/credentials', 
231
    updated_secret, 
232
    cas=3  # Only update if current version is 3
233
)
234
```
235

236
### Custom Authentication
237

238
```python
239
# Using AppRole authentication
240
hook = VaultHook(
241
    vault_conn_id='vault_approle',
242
    auth_type='approle',
243
    role_id='my-role-id'
244
)
245

246
# Using Kubernetes authentication
247
hook = VaultHook(
248
    vault_conn_id='vault_k8s',
249
    auth_type='kubernetes',
250
    kubernetes_role='airflow-role'
251
)
252
```