Skip to content

Commit 36ae1c5

Browse files
YasenTYasenT
authored
docs and other changes (#12)
* docs and other changes
1 parent 3df567d commit 36ae1c5

File tree

7 files changed

+254
-9
lines changed

7 files changed

+254
-9
lines changed

‎README.md‎

Lines changed: 200 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,200 @@
1+
# Pulp CLI Console
2+
3+
A command-line interface for Pulp, providing console administrative functionality.
4+
5+
## Table of Contents
6+
- [Overview](#overview)
7+
- [Requirements](#requirements)
8+
- [Installation](#installation)
9+
- [Configuration](#configuration)
10+
- [Basic Configuration](#basic-configuration)
11+
- [Advanced Options](#advanced-options)
12+
- [Environment Variables](#environment-variables)
13+
- [Usage](#usage)
14+
- [Task Management](#task-management)
15+
- [Vulnerability Management](#vulnerability-management)
16+
- [Performance Monitoring](#performance-monitoring)
17+
- [Troubleshooting](#troubleshooting)
18+
- [Common Issues](#common-issues)
19+
- [Debug Mode](#debug-mode)
20+
- [Logs](#logs)
21+
- [Contributing](#contributing)
22+
- [License](#license)
23+
24+
## Overview
25+
26+
The Pulp CLI Console provides a set of commands to manage Pulp resources from the command line. It extends the base Pulp CLI functionality with console-specific administrative tools for system operators and administrators.
27+
28+
The console offers capabilities for task management, vulnerability scanning, system monitoring, and more, all through a unified command-line interface.
29+
30+
## Requirements
31+
32+
- Python 3.8 or higher
33+
- Access to a Pulp 3.x server
34+
- Network connectivity to your Pulp server
35+
- Appropriate user permissions on the Pulp server
36+
37+
## Installation
38+
39+
You can install the Pulp CLI Console using pip:
40+
41+
```bash
42+
pip install pulp-cli-console
43+
```
44+
45+
For development or the latest features, you can install directly from the repository:
46+
47+
```bash
48+
pip install git+https://github.com/pulp/pulp-cli-console.git
49+
```
50+
51+
## Configuration
52+
53+
### Basic Configuration
54+
55+
The Pulp CLI Console requires configuration to connect to your Pulp server. Create a configuration file at `~/.config/pulp/cli.toml`:
56+
57+
```toml
58+
[cli]
59+
base_url = "https://pulp.example.com"
60+
verify_ssl = true
61+
format = "json"
62+
timeout = 30
63+
username = "admin"
64+
password = "password" # Consider using environment variables instead
65+
```
66+
67+
### Advanced Options
68+
69+
You can customize various aspects of the CLI behavior:
70+
71+
```toml
72+
[cli]
73+
base_url = "https://pulp.example.com"
74+
verify_ssl = true
75+
cert = "/path/to/client/cert.pem" # Optional client certificate
76+
key = "/path/to/client/key.pem" # Optional client key
77+
ca_cert = "/path/to/ca/cert.pem" # Custom CA certificate
78+
format = "json" # Output format: json, yaml, or none
79+
timeout = 60 # Request timeout in seconds
80+
limit = 100 # Default pagination limit
81+
interactive = true # Enable interactive prompts
82+
quiet = false # Suppress non-error output
83+
verbose = 0 # Verbosity level (0-3)
84+
# Use one of the following authentication methods
85+
username = "admin"
86+
password = "password"
87+
token = "your-api-token" # API token authentication
88+
refresh_token = "refresh-token" # For OAuth2 refresh token flow
89+
```
90+
91+
### Environment Variables
92+
93+
You can also use environment variables for configuration, which is recommended for sensitive information:
94+
95+
```bash
96+
# Base configuration
97+
export PULP_BASE_URL="https://pulp.example.com"
98+
export PULP_VERIFY_SSL="true"
99+
100+
# Authentication
101+
export PULP_USERNAME="admin"
102+
export PULP_PASSWORD="password"
103+
104+
# Alternative authentication
105+
export PULP_TOKEN="your-api-token"
106+
```
107+
108+
## Usage
109+
110+
### Task Management
111+
112+
The CLI provides commands for managing administrative tasks:
113+
114+
```bash
115+
# List all tasks
116+
pulp console task list
117+
118+
# Filter tasks by state
119+
pulp console task list --state=completed
120+
121+
# List tasks with pagination
122+
pulp console task list --limit=10 --offset=20
123+
124+
# Filter tasks by name
125+
pulp console task list --name="sync" --name-contains="content"
126+
127+
# Filter tasks by time
128+
pulp console task list --started-at-gte="2023-01-01T00:00:00Z"
129+
130+
# Show detailed information for a specific task
131+
pulp console task show --href=/pulp/api/v3/tasks/1234abcd/
132+
133+
# Cancel a running task
134+
pulp console task cancel --href=/pulp/api/v3/tasks/1234abcd/
135+
```
136+
137+
#### Available Filters for Tasks
138+
139+
- `--limit`: Limit the number of tasks shown
140+
- `--offset`: Skip a number of tasks
141+
- `--name`: Filter by task name
142+
- `--name-contains`: Filter tasks containing this name
143+
- `--logging-cid-contains`: Filter by logging correlation ID
144+
- `--state`: Filter by task state
145+
- `--state-in`: Filter by multiple states (comma-separated)
146+
- `--task-group`: Filter by task group
147+
- `--parent-task`: Filter by parent task
148+
- `--worker`: Filter by worker
149+
- `--created-resources`: Filter by created resources
150+
- `--started-at-gte/--started-at-lte`: Filter by start time
151+
- `--finished-at-gte/--finished-at-lte`: Filter by finish time
152+
- `--reserved-resource/--reserved-resource-in`: Filter by reserved resources
153+
- `--exclusive-resource/--exclusive-resource-in`: Filter by exclusive resources
154+
- `--shared-resource/--shared-resource-in`: Filter by shared resources
155+
156+
### Vulnerability Management
157+
158+
The CLI provides commands for managing vulnerability reports:
159+
160+
```bash
161+
# List vulnerability reports
162+
pulp console vulnerability list
163+
164+
# Show a specific vulnerability report
165+
pulp console vulnerability show --href=/api/pulp/vulnerability-reports/123/
166+
167+
# Create a vulnerability report
168+
pulp console vulnerability create --file=/path/to/packages.json
169+
```
170+
171+
#### Vulnerability Commands
172+
173+
- `list`: List all vulnerability reports
174+
- `show`: Display details of a specific vulnerability report
175+
- `create`: Create a new vulnerability report from a JSON file
176+
177+
#### Options for Vulnerability Commands
178+
179+
- `--href`: Reference to a specific vulnerability report (for show command)
180+
- `--file`: JSON file containing npm packages (required for create command)
181+
- `--chunk-size`: Size of chunks for uploading files (for create command)
182+
- `--severity`: Filter by vulnerability severity (critical, high, medium, low)
183+
- `--status`: Filter by status (open, in-progress, resolved, false-positive)
184+
185+
### Performance Monitoring
186+
187+
```bash
188+
# Get system performance metrics
189+
pulp console monitor performance
190+
191+
# View resource utilization
192+
pulp console monitor resources
193+
194+
# Check Pulp server health
195+
pulp console monitor health
196+
```
197+
198+
## Troubleshooting
199+
200+
### Common Issues

‎pulp-glue-console/pulp_glue/console/__init__.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
__version__ = "0.1.2.dev"
1+
__version__ = "0.1.3.dev"

‎pulp-glue-console/pyproject.toml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
44

55
[project]
66
name = "pulp-glue-console"
7-
version = "0.1.2.dev"
7+
version = "0.1.3.dev"
88
description = "Version agnostic glue library to talk to pulpcore's REST API. (Console plugin)"
99
readme = "README.md"
1010
requires-python = ">=3.8"

‎pulpcore/cli/console/__init__.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,7 @@ def custom_parse_response(
3030
setattr(OpenAPI, parse_response_attr, custom_parse_response)
3131

3232
# Continue with normal mounting
33-
from pulpcore.cli.console.tasks import attach_tasks_commands
33+
from pulpcore.cli.console.task import attach_tasks_commands
3434
from pulpcore.cli.console.vulnerability import attach_vulnerability_commands
3535

3636
@main.group()

pulpcore/cli/console/tasks.py renamed to pulpcore/cli/console/task.py

Lines changed: 44 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -14,11 +14,11 @@ def attach_tasks_commands(console_group: click.Group) -> None:
1414
@console_group.group()
1515
@pass_pulp_context
1616
@click.pass_context
17-
def tasks(ctx: click.Context, pulp_ctx: PulpContext, /) -> None:
17+
def task(ctx: click.Context, pulp_ctx: PulpContext, /) -> None:
1818
"""Manage admin tasks."""
1919
ctx.obj = AdminTaskContext(pulp_ctx)
2020

21-
@tasks.command()
21+
@task.command()
2222
@click.option("--limit", type=int, help="Limit the number of tasks shown")
2323
@click.option("--offset", type=int, help="Skip a number of tasks")
2424
@click.option("--name", help="Filter by task name")
@@ -46,6 +46,36 @@ def tasks(ctx: click.Context, pulp_ctx: PulpContext, /) -> None:
4646
@click.option(
4747
"--finished-at-lte", "finished_at__lte", help="Filter by finish time (less than or equal)"
4848
)
49+
@click.option(
50+
"--reserved-resource",
51+
"reserved_resources",
52+
help="Href of a resource reserved by the task",
53+
)
54+
@click.option(
55+
"--reserved-resource-in",
56+
"reserved_resources__in",
57+
help="Href of a resource reserved by the task (comma-separated)",
58+
)
59+
@click.option(
60+
"--exclusive-resource",
61+
"exclusive_resources",
62+
help="Href of a resource reserved exclusively by the task",
63+
)
64+
@click.option(
65+
"--exclusive-resource-in",
66+
"exclusive_resources__in",
67+
help="Href of a resource reserved exclusively by the task (comma-separated)",
68+
)
69+
@click.option(
70+
"--shared-resource",
71+
"shared_resources",
72+
help="Href of a resource shared by the task",
73+
)
74+
@click.option(
75+
"--shared-resource-in",
76+
"shared_resources__in",
77+
help="Href of a resource shared by the task (comma-separated)",
78+
)
4979
@click.pass_context
5080
@pass_pulp_context
5181
def list(
@@ -67,6 +97,12 @@ def list(
6797
started_at__lte: Optional[str] = None,
6898
finished_at__gte: Optional[str] = None,
6999
finished_at__lte: Optional[str] = None,
100+
reserved_resources: Optional[str] = None,
101+
reserved_resources__in: Optional[str] = None,
102+
exclusive_resources: Optional[str] = None,
103+
exclusive_resources__in: Optional[str] = None,
104+
shared_resources: Optional[str] = None,
105+
shared_resources__in: Optional[str] = None,
70106
) -> None:
71107
task_ctx = ctx.obj
72108
result = task_ctx.list(
@@ -85,5 +121,11 @@ def list(
85121
started_at__lte=started_at__lte,
86122
finished_at__gte=finished_at__gte,
87123
finished_at__lte=finished_at__lte,
124+
reserved_resources=reserved_resources,
125+
reserved_resources__in=reserved_resources__in,
126+
exclusive_resources=exclusive_resources,
127+
exclusive_resources__in=exclusive_resources__in,
128+
shared_resources=shared_resources,
129+
shared_resources__in=shared_resources__in,
88130
)
89131
pulp_ctx.output_result(result)

‎pulpcore/cli/console/vulnerability.py‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,10 @@ def vulnerability(ctx: click.Context, pulp_ctx: PulpContext, /) -> None:
2727

2828
@vulnerability.command()
2929
@click.option(
30-
"--file", type=click.File("rb"), required=True, help="JSON file containing npm packages"
30+
"--file",
31+
type=click.File("rb"),
32+
required=True,
33+
help="Package Lock JSON file with NPM packages to upload",
3134
)
3235
@chunk_size_option
3336
@pass_entity_context

‎pyproject.toml‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
44

55
[project]
66
name = "pulp-cli-console"
7-
version = "0.1.2.dev"
7+
version = "0.1.3.dev"
88
description = "Command line interface to talk to pulpcore's REST API. (Console plugin commands)"
99
readme = "README.md"
1010
requires-python = ">=3.8"
@@ -25,7 +25,7 @@ classifiers=[
2525
]
2626
dependencies = [
2727
"pulp-cli>=0.23.1,<0.33",
28-
"pulp-glue-console==0.1.2.dev"
28+
"pulp-glue-console==0.1.3.dev"
2929
]
3030

3131
[project.urls]
@@ -145,7 +145,7 @@ ignore_missing_imports = true
145145

146146
[tool.bumpversion]
147147
# This section is managed by the cookiecutter templates.
148-
current_version = "0.1.2.dev"
148+
current_version = "0.1.3.dev"
149149
commit = false
150150
tag = false
151151
parse = "(?P<major>\\d+)\\.(?P<minor>\\d+)\\.(?P<patch>\\d+)(\\.(?P<release>[a-z]+))?"

0 commit comments

Comments
 (0)