0
# vdk-plugin-control-cli
1

2
A VDK (Versatile Data Kit) plugin that extends vdk-core with CLI commands for data job lifecycle management and provides integration with Control Service APIs for properties and secrets management. This plugin acts as a bridge between local vdk-core functionality and remote Control Service capabilities, enabling cloud-based data job deployment, management, and execution.
3

4
## Package Information
5

6
- **Package Name**: vdk-plugin-control-cli
7
- **Package Type**: pypi
8
- **Language**: Python
9
- **Installation**: `pip install vdk-plugin-control-cli`
10

11
## Core Imports
12

13
This plugin automatically registers with vdk-core through entry points. No direct imports are typically needed as functionality is exposed through vdk CLI commands and hooks.
14

15
For programmatic access to plugin components:
16

17
```python
18
from vdk.plugin.control_cli_plugin.control_service_configuration import ControlServiceConfiguration
19
from vdk.plugin.control_cli_plugin.control_service_properties_client import ControlServicePropertiesServiceClient
20
from vdk.plugin.control_cli_plugin.control_service_secrets_client import ControlServiceSecretsServiceClient
21
```
22

23
## Basic Usage
24

25
After installation, the plugin extends the vdk CLI with additional commands:
26

27
```bash
28
# Install the plugin
29
pip install vdk-plugin-control-cli
30

31
# Authentication against Control Service
32
vdk login
33

34
# Create a new data job in cloud and locally
35
vdk create my-job --cloud
36

37
# Deploy a data job
38
vdk deploy my-job
39

40
# List data jobs
41
vdk list
42

43
# Manage properties
44
vdk properties --set 'api-uri' 'http://api.example.com'
45

46
# Logout
47
vdk logout
48
```
49

50
## Architecture
51

52
The plugin operates through three main entry points registered with vdk-core:
53

54
1. **vdk-plugin-control-cli**: Main plugin that adds CLI commands and configuration
55
2. **vdk-control-service-properties**: Properties backend using Control Service API
56
3. **vdk-execution-skip**: Execution skip functionality to prevent concurrent job runs
57

58
The plugin integrates with vdk-core's hook system to extend functionality without modifying core behavior.
59

60
## Types
61

62
```python { .api }
63
from typing import Dict
64
import click
65
from vdk.api.plugin.plugin_input import IPropertiesServiceClient, ISecretsServiceClient
66
from vdk.internal.builtin_plugins.run.job_context import JobContext
67
from vdk.internal.core.config import Configuration, ConfigurationBuilder
68
from vdk.internal.core.context import CoreContext
69
```
70

71
## Capabilities
72

73
### CLI Command Integration
74

75
Extends vdk CLI with comprehensive data job lifecycle management commands from vdk-control-cli package.
76

77
```python { .api }
78
@hookimpl(tryfirst=True)
79
def vdk_command_line(root_command: click.Group):
80
    """Hook implementation that adds CLI commands to vdk."""
81
```
82

83
[CLI Commands](./cli-commands.md)
84

85
### Configuration Management
86

87
Comprehensive configuration system for Control Service integration including authentication, HTTP settings, and service endpoints.
88

89
```python { .api }
90
class ControlServiceConfiguration:
91
    def __init__(self, config: Configuration) -> None: ...
92
    def api_token(self): ...
93
    def control_service_rest_api_url(self): ...
94
    def control_http_verify_ssl(self): ...
95
```
96

97
[Configuration](./configuration.md)
98

99
### Properties Backend
100

101
Control Service-based properties storage and retrieval for data jobs, accessible through CLI and JobInput API.
102

103
```python { .api }
104
class ControlServicePropertiesServiceClient(IPropertiesServiceClient):
105
    def __init__(self, rest_api_url: str): ...
106
    def read_properties(self, job_name: str, team_name: str): ...
107
    def write_properties(self, job_name: str, team_name: str, properties: Dict) -> Dict: ...
108
```
109

110
[Properties Backend](./properties-backend.md)
111

112
### Secrets Backend
113

114
Control Service-based secrets storage and retrieval for data jobs, with secure handling and API integration.
115

116
```python { .api }
117
class ControlServiceSecretsServiceClient(ISecretsServiceClient):
118
    def __init__(self, rest_api_url: str): ...
119
    def read_secrets(self, job_name: str, team_name: str): ...
120
    def write_secrets(self, job_name: str, team_name: str, secrets: Dict) -> Dict: ...
121
```
122

123
[Secrets Backend](./secrets-backend.md)
124

125
### Execution Control
126

127
Prevents concurrent execution of the same data job to maintain data consistency and prevent resource conflicts.
128

129
```python { .api }
130
class ConcurrentExecutionChecker:
131
    def __init__(self, rest_api_url: str) -> None: ...
132
    def is_job_execution_running(self, job_name, job_team, job_execution_attempt_id) -> bool: ...
133
```
134

135
[Execution Control](./execution-control.md)
136

137
### Error Handling
138

139
Specialized error handling decorator for Control Service API calls with user-friendly error messages and proper error categorization.
140

141
```python { .api }
142
class ConstrolServiceApiErrorDecorator:
143
    def __init__(self, what="Control Service Error", consequences="Operation cannot complete."): ...
144
    def __call__(self, fn): ...
145
```
146

147
[Error Handling](./error-handling.md)