Skip to content

Commit 44d3e75

Browse files
ibmgeniuzibmgeniuz
committed
docs: Revise README to include OpenStack integration instructions and mode configuration
- Added details for switching between mock and real OpenStack modes. - Documented OpenStack SDK usage, credential setup, and API testing steps. - Updated examples for VM creation with mandatory network parameter. - Clarified testing instructions for unit and integration tests.
1 parent 2ca8963 commit 44d3e75

4 files changed

Lines changed: 194 additions & 16 deletions

File tree

‎.env.example‎

Lines changed: 20 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,26 @@ PORT=8000
1111
# Logging
1212
LOG_LEVEL=INFO
1313

14-
# OpenStack Configuration (for production with real OpenStack)
14+
# OpenStack Configuration
15+
# Set USE_REAL_OPENSTACK=True to use real OpenStack instead of mock
16+
USE_REAL_OPENSTACK=False
17+
18+
# DevStack Configuration (uncomment and configure for your local DevStack)
19+
# Note: DevStack typically runs on a specific IP, not localhost
20+
# Check with: openstack endpoint list | grep identity
21+
# OPENSTACK_AUTH_URL=http://192.168.2.110/identity
22+
# OPENSTACK_USERNAME=admin
23+
# OPENSTACK_PASSWORD=devstack
24+
# OPENSTACK_PROJECT_NAME=demo
25+
# OPENSTACK_PROJECT_DOMAIN_NAME=Default
26+
# OPENSTACK_USER_DOMAIN_NAME=Default
27+
# OPENSTACK_REGION_NAME=RegionOne
28+
#
29+
# Available networks: private, public, shared
30+
# Available images: cirros
31+
# Available flavors: m1.tiny, m1.small, m1.medium, m1.large, m1.xlarge
32+
33+
# Production OpenStack Configuration (alternative to DevStack)
1534
# OPENSTACK_AUTH_URL=http://openstack.example.com:5000/v3
1635
# OPENSTACK_USERNAME=admin
1736
# OPENSTACK_PASSWORD=secret

‎README.md‎

Lines changed: 170 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,9 @@ A REST API for managing OpenStack virtual machine lifecycle operations, built wi
3030

3131
This project provides a comprehensive REST API for managing virtual machine lifecycle in an OpenStack environment. It implements core CRUD operations plus advanced lifecycle management (start, stop, restart, pause, resume) with proper state management and validation.
3232

33-
**Note:** This is a proof-of-concept implementation using mock OpenStack integration. It demonstrates API design and architecture patterns suitable for production use.
33+
**Implementation Modes:**
34+
- **Mock Mode** (default): In-memory storage for development and testing
35+
- **Real OpenStack Mode**: Connect to DevStack or production OpenStack deployment
3436

3537
## Features
3638

@@ -105,15 +107,122 @@ source .venv/bin/activate
105107
pip install -r requirements.txt
106108
```
107109

108-
### 4. Configure Environment (Optional)
110+
### 4. Configure Environment
109111

110112
```bash
111113
# Copy example environment file
112114
cp .env.example .env
113115

114-
# Edit .env with your settings (if needed)
116+
# Edit .env with your settings
117+
# For mock mode (default): No changes needed
118+
# For OpenStack mode: See "OpenStack Integration" section below
115119
```
116120

121+
## OpenStack Integration
122+
123+
### Using Mock Mode (Default)
124+
125+
By default, the API uses an in-memory mock implementation. No additional configuration needed.
126+
127+
```bash
128+
# .env file
129+
USE_REAL_OPENSTACK=False
130+
```
131+
132+
### Using Real OpenStack (DevStack or Production)
133+
134+
To connect to a real OpenStack deployment:
135+
136+
#### 1. Install OpenStack SDK
137+
138+
Already included in `requirements.txt`:
139+
```bash
140+
pip install openstacksdk
141+
```
142+
143+
#### 2. Configure OpenStack Credentials
144+
145+
Edit your `.env` file with your OpenStack credentials:
146+
147+
```bash
148+
# Enable real OpenStack mode
149+
USE_REAL_OPENSTACK=True
150+
151+
# DevStack Configuration (typical local setup)
152+
OPENSTACK_AUTH_URL=http://localhost/identity
153+
OPENSTACK_USERNAME=admin
154+
OPENSTACK_PASSWORD=devstack
155+
OPENSTACK_PROJECT_NAME=demo
156+
OPENSTACK_PROJECT_DOMAIN_NAME=Default
157+
OPENSTACK_USER_DOMAIN_NAME=Default
158+
OPENSTACK_REGION_NAME=RegionOne
159+
```
160+
161+
**Note:** For DevStack, the default admin password is typically `devstack`. Check your DevStack configuration if different.
162+
163+
#### 3. Verify OpenStack Connection
164+
165+
Before starting the API, verify your OpenStack credentials work:
166+
167+
```bash
168+
# Install OpenStack CLI (optional, for testing)
169+
pip install python-openstackclient
170+
171+
# Find your DevStack identity endpoint (usually NOT localhost)
172+
openstack endpoint list | grep identity
173+
# Example output: http://192.168.2.110/identity
174+
175+
# Test connection (replace URL with your endpoint)
176+
openstack --os-auth-url http://192.168.2.110/identity \
177+
--os-username admin \
178+
--os-password devstack \
179+
--os-project-name demo \
180+
--os-user-domain-name Default \
181+
--os-project-domain-name Default \
182+
server list
183+
184+
# Verify available resources
185+
openstack network list # Should show: private, public, shared
186+
openstack image list # Should show: cirros
187+
openstack flavor list # Should show: m1.tiny, m1.small, etc.
188+
```
189+
190+
**Common DevStack URLs:**
191+
- Identity API: `http://<devstack-ip>/identity`
192+
- Compute API: `http://<devstack-ip>/compute/v2.1`
193+
- Network API: `http://<devstack-ip>/networking`
194+
195+
**Note:** DevStack typically runs on the machine's IP address (e.g., `192.168.2.110`), not `localhost`.
196+
197+
#### 4. Start the API with OpenStack
198+
199+
```bash
200+
uvicorn main:app --reload
201+
```
202+
203+
The API will now create, manage, and delete real VMs in your OpenStack deployment.
204+
205+
### OpenStack Requirements
206+
207+
When using real OpenStack mode, ensure your OpenStack deployment has:
208+
- **Flavors**: `m1.tiny`, `m1.small`, `m1.medium`, `m1.large`, `m1.xlarge` (or update flavor names in API calls)
209+
- **Images**: At least one bootable image (e.g., `ubuntu-22.04`, `cirros`)
210+
- **Networks**: At least one network configured for VM connectivity
211+
212+
### Switching Between Modes
213+
214+
You can switch between mock and real OpenStack by changing the `USE_REAL_OPENSTACK` environment variable:
215+
216+
```bash
217+
# Switch to mock mode
218+
USE_REAL_OPENSTACK=False
219+
220+
# Switch to real OpenStack
221+
USE_REAL_OPENSTACK=True
222+
```
223+
224+
Restart the API after changing this setting.
225+
117226
## Running the Application
118227

119228
### Start the API Server
@@ -167,8 +276,9 @@ curl -X POST http://localhost:8000/api/v1/vms \
167276
-H "Content-Type: application/json" \
168277
-d '{
169278
"name": "web-server-01",
170-
"flavor": "m1.medium",
171-
"image": "ubuntu-22.04"
279+
"flavor": "m1.tiny",
280+
"image": "cirros",
281+
"network": "private"
172282
}'
173283
```
174284

@@ -228,7 +338,7 @@ curl -X DELETE http://localhost:8000/api/v1/vms/{vm_id}
228338
# 1. Create a VM
229339
VM_ID=$(curl -s -X POST http://localhost:8000/api/v1/vms \
230340
-H "Content-Type: application/json" \
231-
-d '{"name":"test-vm","flavor":"m1.small","image":"ubuntu-22.04"}' \
341+
-d '{"name":"test-vm","flavor":"m1.tiny","image":"cirros","network":"private"}' \
232342
| jq -r '.id')
233343

234344
echo "Created VM: $VM_ID"
@@ -254,17 +364,51 @@ curl -X DELETE http://localhost:8000/api/v1/vms/$VM_ID
254364

255365
## Testing
256366

257-
### Run All Tests
367+
The project includes comprehensive unit tests and optional integration tests for OpenStack.
368+
369+
### Test Types
370+
371+
**Unit Tests** (default):
372+
- Use mock repository (no external dependencies)
373+
- Fast execution (~0.3s)
374+
- Run automatically in CI/CD
375+
- **Coverage: ~90%**
376+
377+
**Integration Tests** (optional):
378+
- Require real OpenStack connection
379+
- Test actual OpenStack SDK integration
380+
- Slower execution (~30s)
381+
- Run manually with DevStack
382+
383+
### Run Unit Tests
258384

259385
```bash
260-
# Run all tests with coverage
261-
pytest --cov=app --cov-report=html
386+
# Run unit tests only (default behavior)
387+
pytest
388+
389+
# Run with coverage report
390+
pytest --cov=app --cov-report=html --cov-report=term
262391

263392
# Run specific test file
264-
pytest tests/test_vm_service.py
393+
pytest tests/test_vm_service.py -v
394+
395+
# Run specific test
396+
pytest tests/test_vm_service.py::TestVMCreation::test_create_vm_success -v
397+
```
398+
399+
### Run Integration Tests
265400

266-
# Run with verbose output
267-
pytest -v
401+
Integration tests require a running OpenStack instance (DevStack):
402+
403+
```bash
404+
# Run all tests including integration tests
405+
USE_REAL_OPENSTACK=True pytest -m ""
406+
407+
# Run only integration tests
408+
USE_REAL_OPENSTACK=True pytest -m integration -v
409+
410+
# Run integration tests with coverage
411+
USE_REAL_OPENSTACK=True pytest -m "" --cov=app --cov-report=term
268412
```
269413

270414
### View Coverage Report
@@ -282,9 +426,21 @@ xdg-open htmlcov/index.html # Linux
282426
### Test Structure
283427

284428
- `tests/test_vm_service.py` - Unit tests for business logic
285-
- `tests/test_vm_routes.py` - Integration tests for API endpoints
429+
- `tests/test_vm_routes.py` - API endpoint tests
430+
- `tests/test_vm_repository_factory.py` - Factory pattern tests
431+
- `tests/test_openstack_vm_repository.py` - OpenStack integration tests (requires DevStack)
432+
- `tests/openstack_helpers.py` - Test utilities for OpenStack
433+
- `tests/conftest.py` - Global test configuration
434+
435+
### Test Markers
436+
437+
Tests are marked for selective execution:
438+
439+
- `@pytest.mark.unit` - Fast unit tests (default)
440+
- `@pytest.mark.integration` - Integration tests requiring OpenStack
441+
- `@pytest.mark.slow` - Tests that take longer to execute
286442

287-
**Coverage achieved: 90%** (Target: >80%) ✅
443+
**Coverage Target: >85%** | **Current: ~90%** ✅
288444

289445
## Project Structure
290446

‎docs/coverage-report.png‎

-109 KB
Loading

‎requirements.txt‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -24,4 +24,7 @@ flake8==7.0.0
2424
anyio==4.12.1
2525

2626
# Date/Time Handling
27-
python-dateutil==2.9.0
27+
python-dateutil==2.9.0
28+
29+
# OpenStack SDK
30+
openstacksdk==4.10.0

0 commit comments

Comments
 (0)