263 lines
6.7 KiB
Markdown
263 lines
6.7 KiB
Markdown
# EdgeXR Master Controller Go SDK
|
|
|
|
A comprehensive Go SDK for the EdgeXR Master Controller API, providing typed interfaces for edge application lifecycle management, cloudlet orchestration, and instance deployment workflows.
|
|
|
|
## Features
|
|
|
|
- **🔐 Dual Authentication**: Static Bearer tokens and username/password with token caching
|
|
- **📡 Resilient HTTP**: Built-in retry logic, exponential backoff, and context support
|
|
- **⚡ Type Safety**: Full type definitions based on EdgeXR API specifications
|
|
- **🧪 Comprehensive Testing**: Unit tests with mock servers and error condition coverage
|
|
- **📊 Streaming Responses**: Support for EdgeXR's streaming JSON response format
|
|
- **🔧 CLI Integration**: Drop-in replacement for existing edge-connect CLI
|
|
|
|
## Quick Start
|
|
|
|
### Installation
|
|
|
|
```go
|
|
import v2 "edp.buildth.ing/DevFW-CICD/edge-connect-client/v2/sdk/edgeconnect/v2"
|
|
```
|
|
|
|
### Authentication
|
|
|
|
```go
|
|
// Username/password (recommended)
|
|
client := v2.NewClientWithCredentials(baseURL, username, password)
|
|
|
|
// Static Bearer token
|
|
client := v2.NewClient(baseURL,
|
|
v2.WithAuthProvider(v2.NewStaticTokenProvider(token)))
|
|
```
|
|
|
|
### Basic Usage
|
|
|
|
```go
|
|
ctx := context.Background()
|
|
|
|
// Create an application
|
|
app := &v2.NewAppInput{
|
|
Region: "us-west",
|
|
App: v2.App{
|
|
Key: v2.AppKey{
|
|
Organization: "myorg",
|
|
Name: "my-app",
|
|
Version: "1.0.0",
|
|
},
|
|
Deployment: "kubernetes",
|
|
ImagePath: "nginx:latest",
|
|
},
|
|
}
|
|
|
|
if err := v2.CreateApp(ctx, app); err != nil {
|
|
log.Fatal(err)
|
|
}
|
|
|
|
// Deploy an application instance
|
|
instance := &v2.NewAppInstanceInput{
|
|
Region: "us-west",
|
|
AppInst: v2.AppInstance{
|
|
Key: v2.AppInstanceKey{
|
|
Organization: "myorg",
|
|
Name: "my-instance",
|
|
CloudletKey: v2.CloudletKey{
|
|
Organization: "cloudlet-provider",
|
|
Name: "edge-cloudlet",
|
|
},
|
|
},
|
|
AppKey: app.App.Key,
|
|
Flavor: v2.Flavor{Name: "m4.small"},
|
|
},
|
|
}
|
|
|
|
if err := v2.CreateAppInstance(ctx, instance); err != nil {
|
|
log.Fatal(err)
|
|
}
|
|
```
|
|
|
|
## API Coverage
|
|
|
|
### Application Management
|
|
- `CreateApp()` → `POST /auth/ctrl/CreateApp`
|
|
- `ShowApp()` → `POST /auth/ctrl/ShowApp`
|
|
- `ShowApps()` → `POST /auth/ctrl/ShowApp` (multi-result)
|
|
- `DeleteApp()` → `POST /auth/ctrl/DeleteApp`
|
|
|
|
### Application Instance Management
|
|
- `CreateAppInstance()` → `POST /auth/ctrl/CreateAppInst`
|
|
- `ShowAppInstance()` → `POST /auth/ctrl/ShowAppInst`
|
|
- `ShowAppInstances()` → `POST /auth/ctrl/ShowAppInst` (multi-result)
|
|
- `RefreshAppInstance()` → `POST /auth/ctrl/RefreshAppInst`
|
|
- `DeleteAppInstance()` → `POST /auth/ctrl/DeleteAppInst`
|
|
|
|
### Cloudlet Management
|
|
- `CreateCloudlet()` → `POST /auth/ctrl/CreateCloudlet`
|
|
- `ShowCloudlet()` → `POST /auth/ctrl/ShowCloudlet`
|
|
- `ShowCloudlets()` → `POST /auth/ctrl/ShowCloudlet` (multi-result)
|
|
- `DeleteCloudlet()` → `POST /auth/ctrl/DeleteCloudlet`
|
|
- `GetCloudletManifest()` → `POST /auth/ctrl/GetCloudletManifest`
|
|
- `GetCloudletResourceUsage()` → `POST /auth/ctrl/GetCloudletResourceUsage`
|
|
|
|
## Configuration Options
|
|
|
|
```go
|
|
client := v2.NewClient(baseURL,
|
|
// Custom HTTP client with timeout
|
|
v2.WithHTTPClient(&http.Client{Timeout: 30 * time.Second}),
|
|
|
|
// Authentication provider
|
|
v2.WithAuthProvider(v2.NewStaticTokenProvider(token)),
|
|
|
|
// Retry configuration
|
|
v2.WithRetryOptions(v2.RetryOptions{
|
|
MaxRetries: 5,
|
|
InitialDelay: 1 * time.Second,
|
|
MaxDelay: 30 * time.Second,
|
|
}),
|
|
|
|
// Request logging
|
|
v2.WithLogger(log.Default()),
|
|
)
|
|
```
|
|
|
|
## Examples
|
|
|
|
### Simple App Deployment
|
|
```bash
|
|
# Run basic example
|
|
EDGEXR_USERNAME=user EDGEXR_PASSWORD=pass go run sdk/examples/deploy_app.go
|
|
```
|
|
|
|
### Comprehensive Workflow
|
|
```bash
|
|
# Run full workflow demonstration
|
|
cd sdk/examples/comprehensive
|
|
EDGEXR_USERNAME=user EDGEXR_PASSWORD=pass go run main.go
|
|
```
|
|
|
|
## Authentication Methods
|
|
|
|
### Username/Password (Recommended)
|
|
Uses the existing `/api/v1/login` endpoint with automatic token caching:
|
|
|
|
```go
|
|
client := v2.NewClientWithCredentials(baseURL, username, password)
|
|
```
|
|
|
|
**Features:**
|
|
- Automatic token refresh on expiry
|
|
- Thread-safe token caching
|
|
- 1-hour default cache duration
|
|
- Matches existing client authentication exactly
|
|
|
|
### Static Bearer Token
|
|
For pre-obtained tokens:
|
|
|
|
```go
|
|
client := v2.NewClient(baseURL,
|
|
v2.WithAuthProvider(v2.NewStaticTokenProvider(token)))
|
|
```
|
|
|
|
## Error Handling
|
|
|
|
```go
|
|
app, err := v2.ShowApp(ctx, appKey, region)
|
|
if err != nil {
|
|
// Check for specific error types
|
|
if errors.Is(err, v2.ErrResourceNotFound) {
|
|
fmt.Println("App not found")
|
|
return
|
|
}
|
|
|
|
// Check for API errors
|
|
var apiErr *v2.APIError
|
|
if errors.As(err, &apiErr) {
|
|
fmt.Printf("API Error %d: %s\n", apiErr.StatusCode, apiErr.Messages[0])
|
|
return
|
|
}
|
|
|
|
// Network or other errors
|
|
fmt.Printf("Request failed: %v\n", err)
|
|
}
|
|
```
|
|
|
|
## Testing
|
|
|
|
```bash
|
|
# Run all SDK tests
|
|
go test ./sdk/client/ -v
|
|
|
|
# Run with coverage
|
|
go test ./sdk/client/ -v -coverprofile=coverage.out
|
|
go tool cover -html=coverage.out
|
|
|
|
# Run specific test suites
|
|
go test ./sdk/client/ -v -run TestApp
|
|
go test ./sdk/client/ -v -run TestAuth
|
|
go test ./sdk/client/ -v -run TestCloudlet
|
|
```
|
|
|
|
## CLI Integration
|
|
|
|
The existing `edge-connect` CLI has been updated to use the SDK internally while maintaining full backward compatibility:
|
|
|
|
```bash
|
|
# Same commands, enhanced reliability
|
|
edge-connect app create --org myorg --name myapp --version 1.0.0 --region us-west
|
|
edge-connect instance create --org myorg --name myinst --app myapp --version 1.0.0
|
|
```
|
|
|
|
## Migration from Existing Client
|
|
|
|
The SDK provides a drop-in replacement with enhanced features:
|
|
|
|
```go
|
|
// Old approach
|
|
oldClient := &v2.EdgeConnect{
|
|
BaseURL: baseURL,
|
|
Credentials: v2.Credentials{Username: user, Password: pass},
|
|
}
|
|
|
|
// New SDK approach
|
|
newClient := v2.NewClientWithCredentials(baseURL, user, pass)
|
|
|
|
// Same method calls, enhanced reliability
|
|
err := newClient.CreateApp(ctx, input)
|
|
```
|
|
|
|
## Performance
|
|
|
|
- **Token Caching**: Reduces login API calls by >90%
|
|
- **Connection Pooling**: Reuses HTTP connections efficiently
|
|
- **Context Support**: Proper timeout and cancellation handling
|
|
- **Retry Logic**: Automatic recovery from transient failures
|
|
|
|
## Contributing
|
|
|
|
### Project Structure
|
|
```
|
|
sdk/
|
|
├── client/ # Public SDK interfaces
|
|
├── internal/http/ # HTTP transport layer
|
|
├── examples/ # Usage demonstrations
|
|
└── README.md # This file
|
|
```
|
|
|
|
### Development
|
|
```bash
|
|
# Install dependencies
|
|
go mod tidy
|
|
|
|
# Generate types (if swagger changes)
|
|
make generate
|
|
|
|
# Run tests
|
|
make test
|
|
|
|
# Build everything
|
|
make build
|
|
```
|
|
|
|
## License
|
|
|
|
This SDK follows the same license as the parent edge-connect-client project.
|