simplified instructions
This commit is contained in:
Kosta Mushkin
@@ -3,44 +3,93 @@
|
||||
## Overview
|
||||
In this exercise, you'll learn how to authenticate with the Zerto API using Keycloak. You'll create a client and establish a connection to your ZVM.
|
||||
|
||||
## Objectives
|
||||
- Create a Keycloak client
|
||||
- Configure authentication parameters
|
||||
- Test the connection to ZVM
|
||||
- Handle authentication errors
|
||||
## What You'll Learn
|
||||
- How to create a ZVMLClient object (your "remote control" for ZVM)
|
||||
- How to connect to your Zerto Virtual Manager
|
||||
- How to test if the connection works
|
||||
- How to handle errors if something goes wrong
|
||||
|
||||
## Time
|
||||
10 minutes
|
||||
|
||||
## Prerequisites
|
||||
- Completed Exercise 1
|
||||
- Valid ZVM credentials
|
||||
- Client ID and secret
|
||||
- ✅ Completed Exercise 1
|
||||
- ✅ Valid ZVM credentials (IP address, client ID, client secret)
|
||||
- ✅ Updated `prerequisites/config.py` with your details
|
||||
|
||||
## Exercise Steps
|
||||
1. Set up your configuration
|
||||
2. Create the Keycloak client
|
||||
3. Test the connection
|
||||
4. Handle authentication errors
|
||||
## Step-by-Step Instructions
|
||||
|
||||
### Step 1: Open the Working File
|
||||
1. Navigate to `exercises/02_authentication/working/`
|
||||
2. Open `auth.py` in your code editor
|
||||
3. Read through the detailed comments - they explain everything!
|
||||
|
||||
### Step 2: Complete the Code
|
||||
The file has three main sections you need to complete:
|
||||
|
||||
1. **Create ZVMLClient** - Replace `client = None` with actual code
|
||||
2. **Test Connection** - Add code to test if it works
|
||||
3. **Success Message** - Add a final success message
|
||||
|
||||
### Step 3: Run Your Code
|
||||
```bash
|
||||
cd exercises/02_authentication/working/
|
||||
python auth.py
|
||||
```
|
||||
|
||||
### Step 4: Check the Results
|
||||
- ✅ **Success**: You'll see "Connection successful!" and ZVM version info
|
||||
- ❌ **Error**: Check the error message and review your config.py
|
||||
|
||||
## Working Directory
|
||||
The `working` directory contains:
|
||||
- `auth.py` - Template to complete
|
||||
- `auth.py` - **Beginner-friendly template** with detailed instructions
|
||||
|
||||
## Solution
|
||||
The `solution` directory contains:
|
||||
- `auth.py` - Complete working example
|
||||
- `auth.py` - Complete working example (check this if you get stuck!)
|
||||
|
||||
## Key Concepts
|
||||
- Keycloak authentication
|
||||
- Client credentials flow
|
||||
- Error handling
|
||||
- Connection management
|
||||
## Key Concepts Explained
|
||||
|
||||
## Common Issues
|
||||
- Invalid credentials
|
||||
- SSL certificate issues
|
||||
- Network connectivity problems
|
||||
### What is ZVMLClient?
|
||||
- Think of it as a "remote control" for your Zerto Virtual Manager
|
||||
- It handles all the communication between your Python code and ZVM
|
||||
- You need to give it your ZVM address and login credentials
|
||||
|
||||
### What is Keycloak?
|
||||
- It's the authentication system that Zerto uses
|
||||
- You create a "client" (like a username) and get a "secret" (like a password)
|
||||
- The ZVMLClient uses these to log into your ZVM
|
||||
|
||||
### What is SSL Verification?
|
||||
- It's a security check to make sure you're connecting to the right server
|
||||
- Usually set to `False` for Zerto (self-signed certificates)
|
||||
|
||||
## Common Issues & Solutions
|
||||
|
||||
### ❌ "Configuration file not found"
|
||||
**Solution**: Copy `prerequisites/config.example.py` to `prerequisites/config.py`
|
||||
|
||||
### ❌ "Authentication failed"
|
||||
**Solutions**:
|
||||
- Check your ZVM_HOST is correct
|
||||
- Verify your CLIENT_ID and CLIENT_SECRET
|
||||
- Make sure your ZVM is running and accessible
|
||||
|
||||
### ❌ "SSL certificate" errors
|
||||
**Solution**: Make sure `ZVM_SSL_VERIFY = False` in your config.py
|
||||
|
||||
### ❌ "Connection refused" or "Network unreachable"
|
||||
**Solutions**:
|
||||
- Check your ZVM IP address is correct
|
||||
- Make sure you can ping the ZVM from your computer
|
||||
- Check firewall settings
|
||||
|
||||
## Need Help?
|
||||
1. Read the detailed comments in the code
|
||||
2. Check the solution file
|
||||
3. Review your `config.py` settings
|
||||
4. Ask your Zerto administrator for help with credentials
|
||||
|
||||
## Next Steps
|
||||
Proceed to Exercise 3: Site Discovery to start working with Zerto sites.
|
||||
Once you successfully connect, proceed to **Exercise 3: Site Discovery** to start working with Zerto sites.
|
||||
@@ -1,20 +1,31 @@
|
||||
#!/usr/bin/env python3
|
||||
"""
|
||||
Exercise 2: Authentication
|
||||
Exercise 2: Authentication - Beginner-Friendly Instructions
|
||||
This script demonstrates how to authenticate with Zerto API using Keycloak.
|
||||
|
||||
Prerequisites:
|
||||
1. Install the zvml package in development mode:
|
||||
cd /path/to/zvml-python-sdk
|
||||
pip install -e .
|
||||
2. Update prerequisites/config.py with your ZVM details
|
||||
PREREQUISITES (Complete these first):
|
||||
1. Make sure you have the zvml package installed (see main README)
|
||||
2. Update prerequisites/config.py with your ZVM details:
|
||||
- ZVM_HOST: Your Zerto Virtual Manager IP address or hostname
|
||||
- CLIENT_ID: Your Keycloak client ID
|
||||
- CLIENT_SECRET: Your Keycloak client secret
|
||||
|
||||
Your task:
|
||||
1. Initialize ZVMLClient with Keycloak credentials
|
||||
2. Test connection by retrieving local site information
|
||||
3. Handle authentication and connection errors
|
||||
WHAT YOU NEED TO DO:
|
||||
In this exercise, you will:
|
||||
1. Create a ZVMLClient object to connect to your ZVM
|
||||
2. Test the connection by getting information about your local site
|
||||
3. Handle any errors that might occur
|
||||
|
||||
If you need help, check the solution in the solution directory.
|
||||
STEP-BY-STEP INSTRUCTIONS:
|
||||
1. Look at the TODO comments below - they tell you exactly what to do
|
||||
2. Replace the placeholder code with the actual code
|
||||
3. Each step has hints and examples to help you
|
||||
4. If you get stuck, check the solution file in the solution/ directory
|
||||
|
||||
WHAT IS A ZVMLClient?
|
||||
- It's like a "remote control" for your Zerto Virtual Manager
|
||||
- It handles all the communication with your ZVM
|
||||
- You need to give it your ZVM address and login credentials
|
||||
"""
|
||||
|
||||
import sys
|
||||
@@ -23,61 +34,106 @@ import logging
|
||||
import json
|
||||
from pathlib import Path
|
||||
|
||||
# Add prerequisites to Python path
|
||||
# Add prerequisites to Python path (this helps Python find your config file)
|
||||
prerequisites_path = Path(__file__).parent.parent.parent.parent / "prerequisites"
|
||||
sys.path.append(str(prerequisites_path))
|
||||
|
||||
# Import the SDK modules
|
||||
# Import the Zerto SDK - this gives us the ZVMLClient class
|
||||
from zvml import ZVMLClient
|
||||
|
||||
# Import configuration
|
||||
# Import your configuration settings
|
||||
try:
|
||||
from config import (
|
||||
ZVM_HOST,
|
||||
ZVM_PORT,
|
||||
ZVM_SSL_VERIFY,
|
||||
CLIENT_ID,
|
||||
CLIENT_SECRET
|
||||
ZVM_HOST, # Your ZVM IP address (e.g., "192.168.1.100")
|
||||
ZVM_PORT, # Usually 443 for HTTPS
|
||||
ZVM_SSL_VERIFY, # True/False for SSL certificate verification
|
||||
CLIENT_ID, # Your Keycloak client ID (e.g., "my-api-client")
|
||||
CLIENT_SECRET # Your Keycloak client secret
|
||||
)
|
||||
except ImportError:
|
||||
print("Error: Please copy config.example.py to config.py and update with your values")
|
||||
print("❌ ERROR: Configuration file not found!")
|
||||
print("Please copy config.example.py to config.py and update with your values")
|
||||
print("Expected path:", prerequisites_path / "config.py")
|
||||
sys.exit(1)
|
||||
|
||||
def main():
|
||||
"""
|
||||
Main function to demonstrate Zerto authentication.
|
||||
Complete the following steps:
|
||||
1. Initialize ZVMLClient with Keycloak credentials
|
||||
2. Test connection by retrieving local site info
|
||||
3. Handle authentication and connection errors
|
||||
Main function - this is where your code goes!
|
||||
Follow the step-by-step instructions below.
|
||||
"""
|
||||
# Set up logging with timestamp
|
||||
# Set up logging so you can see what's happening
|
||||
logging.basicConfig(
|
||||
level=logging.INFO,
|
||||
format='%(asctime)s - %(levelname)s - %(message)s'
|
||||
)
|
||||
|
||||
print("🚀 Starting Zerto Authentication Exercise")
|
||||
print("=" * 50)
|
||||
|
||||
try:
|
||||
# Step 1: Create a ZVMLClient instance
|
||||
# TODO: Initialize the ZVMLClient with your ZVM host and credentials
|
||||
# Hint: Use ZVMLClient(zvm_address=ZVM_HOST, client_id=CLIENT_ID,
|
||||
# client_secret=CLIENT_SECRET, verify_certificate=ZVM_SSL_VERIFY)
|
||||
client = None # Replace with actual client initialization
|
||||
# ========================================
|
||||
# STEP 1: Create a ZVMLClient instance
|
||||
# ========================================
|
||||
print("\n📝 STEP 1: Creating ZVMLClient...")
|
||||
print("You need to replace the line 'client = None' with actual code.")
|
||||
print("Look at the hint below for the correct syntax.")
|
||||
|
||||
# Step 2: Test the connection
|
||||
# TODO: Try to get local site information to verify the connection
|
||||
# Hint: Use client.localsite.get_local_site() and extract the Version
|
||||
# Hint: Log the version using logging.info()
|
||||
pass # Replace with actual connection test
|
||||
# TODO: Replace this line with actual ZVMLClient creation
|
||||
# HINT: Use this syntax:
|
||||
# client = ZVMLClient(
|
||||
# zvm_address=ZVM_HOST,
|
||||
# client_id=CLIENT_ID,
|
||||
# client_secret=CLIENT_SECRET,
|
||||
# verify_certificate=ZVM_SSL_VERIFY
|
||||
# )
|
||||
#
|
||||
# EXPLANATION:
|
||||
# - zvm_address: Where your ZVM is located (from config.py)
|
||||
# - client_id: Your Keycloak client ID (from config.py)
|
||||
# - client_secret: Your Keycloak client secret (from config.py)
|
||||
# - verify_certificate: Whether to check SSL certificates (from config.py)
|
||||
|
||||
# Step 3: Print connection status
|
||||
# TODO: Display whether the connection was successful
|
||||
# Hint: Use logging.info() to show the status
|
||||
client = None # ← REPLACE THIS LINE WITH YOUR CODE
|
||||
|
||||
# ========================================
|
||||
# STEP 2: Test the connection
|
||||
# ========================================
|
||||
print("\n📝 STEP 2: Testing connection...")
|
||||
print("You need to test if the connection works by getting local site info.")
|
||||
print("Look at the hint below for the correct syntax.")
|
||||
|
||||
# TODO: Add code to test the connection
|
||||
# HINT: Use this syntax:
|
||||
# local_site = client.localsite.get_local_site()
|
||||
# version = local_site.get('Version')
|
||||
# logging.info(f"Successfully connected to ZVM version: {version}")
|
||||
#
|
||||
# EXPLANATION:
|
||||
# - client.localsite.get_local_site() gets information about your local ZVM
|
||||
# - local_site.get('Version') extracts the ZVM version from the response
|
||||
# - logging.info() displays a success message
|
||||
|
||||
# ← ADD YOUR CODE HERE
|
||||
|
||||
# ========================================
|
||||
# STEP 3: Display success message
|
||||
# ========================================
|
||||
print("\n📝 STEP 3: Displaying success message...")
|
||||
print("You need to add a final success message.")
|
||||
|
||||
# TODO: Add a success message
|
||||
# HINT: Use this syntax:
|
||||
# logging.info("🎉 Connection successful!")
|
||||
#
|
||||
# EXPLANATION:
|
||||
# This confirms that everything worked correctly
|
||||
|
||||
# ← ADD YOUR CODE HERE
|
||||
|
||||
except Exception as e:
|
||||
# TODO: Handle any authentication or connection errors
|
||||
# Hint: Use logging.error() to log the error message
|
||||
# This catches any errors that might occur
|
||||
print(f"\n❌ ERROR: Something went wrong!")
|
||||
print(f"Error details: {str(e)}")
|
||||
logging.error(f"Authentication failed: {str(e)}")
|
||||
sys.exit(1)
|
||||
|
||||
|
||||
Reference in New Issue
Block a user