This release is a pre-release and may not be stable for production use.
Waldur Site Agent OKD Plugin
This plugin enables Waldur Site Agent to manage OKD/OpenShift projects and resources, providing integration between Waldur and OKD/OpenShift clusters.
At a glance
| Entry point | Group | Role |
|---|---|---|
okd |
waldur_site_agent.backends |
order processing, membership sync, reporting |
Modes: order_process, membership_sync, report, event_process.
| Operation | Behaviour |
|---|---|
| Create resource | Creates an OpenShift project (ProjectRequest) and a ResourceQuota from the ordered limits |
| Terminate resource | Deletes the project |
| Update limits | Updates the ResourceQuota |
| Add / remove members | Creates / deletes a RoleBinding with default_role |
| Pause | Sets every quota to zero |
| Downscale | Sets the quota to 1 core, 1 GB memory, 1 GB storage, 1 pod |
| Restore | Sets fixed default quotas (10 cores, 32 GB, 100 GB, 50 pods), not the ordered limits |
| Usage reporting | Current usage read from the ResourceQuota |
Features
- Automatic project/namespace creation for Waldur resources
- Resource quota management (CPU, memory, storage, pod limits)
- User access control through RoleBindings
- Resource usage reporting
- Project lifecycle management (create, pause, restore, delete)
Installation
Install the plugin alongside the core waldur-site-agent package:
# From a checkout of this repository: install the core and every plugin
uv sync --all-packages
# Or from PyPI, into the same environment as the agent
pip install waldur-site-agent waldur-site-agent-okd
Configuration
Add an offering to the agent configuration (see examples/okd-config.yaml for a complete file):
offerings:
- name: "OKD projects"
waldur_api_url: "https://waldur.example.com/api/"
waldur_api_token: "<waldur api token>"
waldur_offering_uuid: "<okd offering uuid>"
backend_type: "okd"
order_processing_backend: "okd"
membership_sync_backend: "okd"
reporting_backend: "okd"
backend_settings:
api_url: "https://api.okd.example.com:6443"
token: "<service account token>"
verify_cert: true
namespace_prefix: "waldur-"
default_role: "edit"
backend_components:
cpu:
measured_unit: "Core"
accounting_type: "limit"
label: "CPU cores"
unit_factor: 1
memory:
measured_unit: "GB"
accounting_type: "limit"
label: "Memory"
unit_factor: 1
storage:
measured_unit: "GB"
accounting_type: "limit"
label: "Storage"
unit_factor: 1
pods:
measured_unit: "Count"
accounting_type: "limit"
label: "Pods"
unit_factor: 1
Backend settings
Validated by waldur_site_agent_okd.schemas.OkdBackendSettingsSchema; a
misspelt key is logged as a warning when the agent loads its configuration.
| Setting | Required | Default | Description |
|---|---|---|---|
api_url |
no | https://localhost:8443 |
OpenShift/OKD API URL |
token |
no | empty | Static bearer token (ignored when token_config is set) |
token_config |
no | — | Token refresh, see below |
verify_cert |
no | true |
Verify the API's TLS certificate; a path names a CA bundle |
namespace_prefix |
no | waldur- |
Prefix of managed namespaces |
customer_prefix |
no | org- |
Prefix of customer-level ids |
project_prefix |
no | proj- |
Prefix of project-level ids |
allocation_prefix |
no | alloc- |
Prefix of allocation namespaces |
default_role |
no | edit |
ClusterRole bound to members |
Authentication Token Management
The plugin supports multiple authentication methods with automatic token refresh:
Static Token (Simple)
For testing or when manually managing tokens:
backend_settings:
api_url: https://api.okd.example.com:8443
token: sha256~your-static-token-here
verify_cert: true
Service Account Token (Production Recommended)
For production deployments with automatic token refresh:
backend_settings:
api_url: https://api.okd.example.com:8443
verify_cert: true
token_config:
token_type: service_account
service_account_path: /var/run/secrets/kubernetes.io/serviceaccount
File-Based Token Refresh
When tokens are managed by external systems:
backend_settings:
api_url: https://api.okd.example.com:8443
verify_cert: true
token_config:
token_type: file
token_file_path: /etc/okd-tokens/current-token
OAuth Token Refresh (Future)
Framework ready for OAuth-based authentication:
backend_settings:
api_url: https://api.okd.example.com:8443
verify_cert: true
token_config:
token_type: oauth
oauth_config:
client_id: your-oauth-client-id
client_secret: your-oauth-client-secret
refresh_token: your-refresh-token
token_endpoint: https://oauth.okd.example.com/oauth/token
Waldur to OKD Object Mapping
The plugin maps Waldur organizational hierarchy to OKD/OpenShift projects and namespaces:
graph TB
subgraph "Waldur Hierarchy"
WC[Customer/Organization<br/>e.g. 'ACME Corp']
WP[Project<br/>e.g. 'Web Development']
WR[Resource/Allocation<br/>e.g. 'Production Environment']
WU[Users<br/>e.g. 'john@acme.com']
WC --> WP
WP --> WR
WC --> WU
WP --> WU
end
subgraph "OKD/OpenShift Objects"
ON[Namespace/Project<br/>waldur-alloc-prod-env]
ORQ[ResourceQuota<br/>waldur-quota]
ORB[RoleBinding<br/>waldur-users]
OSA[ServiceAccounts]
ON --> ORQ
ON --> ORB
ON --> OSA
end
subgraph "Mapping Rules"
MR1[Customer → Project Prefix]
MR2[Project → Project Metadata]
MR3[Resource → Namespace]
MR4[Users → RoleBindings]
MR5[Limits → ResourceQuota]
end
WC -.->|Prefix| ON
WP -.->|Metadata| ON
WR ==>|Creates| ON
WU -.->|Binds to| ORB
WR -.->|Sets limits| ORQ
style WR fill:#e1f5fe
style ON fill:#c8e6c9
style ORQ fill:#fff9c4
style ORB fill:#ffccbc
Object Mapping Details
1. Namespace Creation
Waldur resources are mapped to OKD namespaces with a hierarchical naming convention:
| Waldur Object | OKD Namespace Pattern | Example |
|---|---|---|
| Customer Resource | {prefix}org-{customer_slug} |
waldur-org-acme |
| Project Resource | {prefix}proj-{project_slug} |
waldur-proj-webdev |
| Allocation Resource | {prefix}alloc-{allocation_slug} |
waldur-alloc-prod-env |
2. Resource Quotas
Waldur resource limits are translated to Kubernetes ResourceQuotas:
| Waldur Component | OKD ResourceQuota Field | Example |
|---|---|---|
| CPU (Cores) | requests.cpu, limits.cpu (2x requests) |
requests: 4, limits: 8 |
| Memory (GB) | requests.memory, limits.memory (2x requests) |
requests: 16Gi, limits: 32Gi |
| Storage (GB) | requests.storage |
100Gi |
| Pod Count | pods |
50 |
Note:
limits.cpuandlimits.memoryare automatically set to 2x the request values to allow bursting.
3. User Access Mapping
Waldur user roles are mapped to OpenShift RoleBindings:
| Waldur Role | OpenShift ClusterRole | Permissions |
|---|---|---|
| Owner | admin |
Full namespace administration |
| Manager | edit |
Create/modify resources |
| Member | view |
Read-only access |
4. Metadata and Annotations
Waldur metadata is preserved in OKD annotations:
metadata:
name: waldur-alloc-prod-env
annotations:
openshift.io/description: "Production Environment"
openshift.io/display-name: "Production Environment"
waldur/organization: "waldur-org-acme"
waldur/parent: "waldur-proj-webdev"
OKD/OpenShift Setup
Authentication Requirements
The plugin requires a service account token with specific permissions to manage OKD/OpenShift resources. The token must have cluster-level permissions to create and manage projects, namespaces, resource quotas, and role bindings.
Required Permissions
The service account needs the following permissions:
- Project Management: Create, delete, and modify OpenShift projects
- Namespace Management: Manage Kubernetes namespaces and their metadata
- Resource Quota Management: Create and modify resource quotas for namespace limits
- Role Binding Management: Assign users to projects with appropriate roles
- Resource Monitoring: Query resource usage and project status
1. Create Service Account
Create a service account for the Waldur Site Agent:
# Create service account in the desired namespace
oc create serviceaccount waldur-site-agent -n waldur-system
# Alternative: Use the default namespace
oc create serviceaccount waldur-site-agent -n default
2. Grant Permissions
Create a ClusterRole with necessary permissions:
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
name: waldur-site-agent
rules:
# OpenShift project management
- apiGroups: ["project.openshift.io"]
resources: ["projects", "projectrequests"]
verbs: ["create", "delete", "get", "list", "patch", "update"]
# Kubernetes namespace and resource quota management
- apiGroups: [""]
resources: ["namespaces", "resourcequotas"]
verbs: ["create", "delete", "get", "list", "patch", "update"]
# User access management through role bindings
- apiGroups: ["rbac.authorization.k8s.io"]
resources: ["rolebindings"]
verbs: ["create", "delete", "get", "list", "patch", "update"]
# Resource monitoring and usage reporting
- apiGroups: [""]
resources: ["pods", "services", "persistentvolumeclaims"]
verbs: ["get", "list"]
# API discovery for cluster connectivity checks
- apiGroups: [""]
resources: [""]
verbs: ["get"]
Bind the role to the service account:
# Bind the cluster role to the service account
oc adm policy add-cluster-role-to-user waldur-site-agent -z waldur-site-agent -n waldur-system
# Alternative: Using oc create command
oc create clusterrolebinding waldur-site-agent \
--clusterrole=waldur-site-agent \
--serviceaccount=waldur-system:waldur-site-agent
3. Get Service Account Token
For Production Deployment (Recommended)
Create a long-lived token for production use:
# OpenShift 4.11+ (recommended for production)
oc create token waldur-site-agent \
--namespace=waldur-system \
--duration=8760h \
--bound-object-kind=Secret \
--bound-object-name=waldur-site-agent-token
# Create a secret-bound token for enhanced security
oc apply -f - <<EOF
apiVersion: v1
kind: Secret
metadata:
name: waldur-site-agent-token
namespace: waldur-system
annotations:
kubernetes.io/service-account.name: waldur-site-agent
type: kubernetes.io/service-account-token
EOF
# Get the token from the secret
oc get secret waldur-site-agent-token -n waldur-system -o jsonpath='{.data.token}' | base64 -d
For Development/Testing
Create a temporary token for testing:
# OpenShift 4.x (24 hour expiration)
oc create token waldur-site-agent --namespace=waldur-system
# OpenShift 3.x (legacy method)
oc sa get-token waldur-site-agent -n waldur-system
Token Validation
Verify the token has correct permissions:
# Test basic API access
curl -k -H "Authorization: Bearer YOUR_TOKEN" \
"https://your-okd-api:6443/api/v1"
# Test project creation permissions
curl -k -H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
"https://your-okd-api:6443/apis/project.openshift.io/v1/projectrequests" \
-X POST -d '{
"kind": "ProjectRequest",
"apiVersion": "project.openshift.io/v1",
"metadata": {"name": "test-waldur-permissions"},
"displayName": "Test Permissions"
}'
# Clean up test project
oc delete project test-waldur-permissions
Usage
Run the agent with your configuration:
waldur_site_agent -m event_process -c okd-config.yaml
Supported Modes
order_process: Process orders from Waldur to create/modify OKD projectsreport: Report resource usage from OKD to Waldurmembership_sync: Synchronize user memberships between Waldur and OKDevent_process: Process events via STOMP (if configured)
Event processing
Event mode needs nothing OKD-specific: enable STOMP on the offering
(stomp_enabled: true, see Configuration) and run
the agent with -m event_process.
Resource Management
Quotas
Resource quotas are automatically created for each project based on Waldur resource allocations. The quotas enforce both request and limit constraints for:
- CPU cores: Managed through
requests.cpuandlimits.cpu - Memory: Managed through
requests.memoryandlimits.memory - Storage: Managed through persistent volume claims
- Pod count: Maximum number of pods in the namespace
Lifecycle Operations
The plugin supports pausing, downscaling, and restoring projects by adjusting their resource quotas. These operations use hardcoded values (not configurable):
| Operation | CPU | Memory | Storage | Pods |
|---|---|---|---|---|
| Pause | 0 | 0 GB | 0 GB | 0 |
| Downscale | 1 core | 1 GB | 1 GB | 1 |
| Restore (defaults) | 10 cores | 32 GB | 100 GB | 50 |
Note: The restore operation currently applies hardcoded default quotas rather than restoring previously configured values.
User Access
Users from Waldur are automatically granted access to OKD projects through RoleBindings. The plugin maps Waldur roles to OpenShift ClusterRoles for fine-grained access control.
Testing
Run the plugin tests:
# From the plugin directory, so its entry points resolve
cd plugins/okd && uv run pytest tests/
Troubleshooting
Token Refresh Behavior
The plugin automatically handles token expiration and refresh:
- Automatic Detection: Monitors for 401/403 authentication errors
- Refresh Triggers: Automatically refreshes tokens before expiration (5 minutes buffer)
- Fallback Handling: Gracefully handles token refresh failures
- Retry Logic: Automatically retries failed requests with refreshed tokens
Token Refresh Flow
- Initial Request: Uses current token for API calls
- Failure Detection: Detects 401 Unauthorized responses
- Token Refresh: Invalidates current token and loads new one
- Request Retry: Retries the original request with the new token
- Error Handling: Reports refresh failures with detailed error messages
Authentication Issues
If authentication fails:
-
Verify Token Validity:
# Test token directly curl -k -H "Authorization: Bearer YOUR_TOKEN" \ "https://your-okd-api:6443/api/v1"
-
Check Token Expiration:
# Decode JWT token (if using JWT format) echo "YOUR_TOKEN" | cut -d'.' -f2 | base64 -d | jq .exp
-
Validate Service Account Permissions:
# Check if service account exists oc get serviceaccount waldur-site-agent -n waldur-system # Verify cluster role binding oc get clusterrolebinding waldur-site-agent
Connection Issues
If the agent cannot connect to the OKD cluster:
- Verify the API URL is correct and accessible
- Check the service account token is valid and not expired
- For self-signed certificates, set
verify_cert: false - Ensure network connectivity to the cluster
Permission Errors
If operations fail with permission errors:
- Verify the service account has the required ClusterRole permissions
- Check the ClusterRoleBinding is correctly configured
- Ensure the token has not expired (check logs for 401 errors)
- Validate that the service account namespace exists
Token Refresh Issues
If automatic token refresh fails:
- File-based tokens: Ensure the token file path is readable and contains valid token
- Service account tokens: Verify the service account path is mounted correctly
- Static tokens: Replace expired static tokens manually
- OAuth tokens: Check OAuth configuration and refresh token validity
Debug Mode
Enable debug logging for detailed token management information:
Set the top-level log_level: DEBUG in the agent configuration.
Diagnostics
Run diagnostics to verify configuration:
# Standard diagnostics
waldur_site_diagnostics -c okd-config.yaml
Development
Plugin Structure
waldur_site_agent_okd/ holds the backend, the API client, the token manager
and the settings schema; tests are in tests/, example configurations in
examples/ (cluster RBAC for the agent's service account in
examples/kubernetes/).
Key Components
backend.py: Main plugin implementation extendingBaseBackendclient.py: OKD API client with SSL adapter and authentication integrationtoken_manager.py: Comprehensive token management system supporting:- Static tokens for testing
- File-based token refresh
- Service account token mounting
- OAuth refresh framework (future)
Adding New Features
- Extend the
OkdClientclass for new API operations - Update the
OkdBackendclass to use new client methods - Add tests for new functionality
- Update configuration examples if needed
License
This plugin is part of the Waldur Site Agent project and follows the same license terms.
Metadata
Release files for waldur-site-agent-okd 1.0.8rc13
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| waldur_site_agent_okd-1.0.8rc13.tar.gz | 19.9 kB | Without provenance | Details for waldur_site_agent_okd-1.0.8rc13.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| waldur_site_agent_okd-1.0.8rc13-py3-none-any.whl | Python 3 | none | any | Details for waldur_site_agent_okd-1.0.8rc13-py3-none-any.whl |
Total release size: 38.7 kB
Release files / waldur_site_agent_okd-1.0.8rc13.tar.gz
| Download URL | waldur_site_agent_okd-1.0.8rc13.tar.gz |
|---|---|
| Size | 19.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
da50654fc82659c44f577f78a04e5c3b0cefe0bbbbaab0030a537513e08ac328
|
|
BLAKE2b-256 checksum How to use checksums |
d82985cee9078a3bab0713bdccba1b1e503ad388816ad40db52faeaedb7a01cb
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.13.7 {"installer":{"name":"uv","version":"0.13.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"12","id":"bookworm","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / waldur_site_agent_okd-1.0.8rc13-py3-none-any.whl
| Download URL | waldur_site_agent_okd-1.0.8rc13-py3-none-any.whl |
|---|---|
| Size | 18.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
3c7533f1c2b03bacef971ab958e1b244e96a44e8c663c0768e0f59cce3d1d586
|
|
BLAKE2b-256 checksum How to use checksums |
257e23e184f66f0882aabc9959525c830ecaa3eabb1681117419210e82c6c909
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.13.7 {"installer":{"name":"uv","version":"0.13.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"12","id":"bookworm","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Security for waldur-site-agent-okd 1.0.8rc13
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.