cheatsheets/vxrail-api-cheatsheet.md

VxRail API Cheatsheet

Overview

VxRail is Dell EMC's hyper-converged infrastructure platform. The REST API allows programmatic management of clusters, hosts, lifecycle operations, and more. This cheatsheet is based on official documentation from Dell Technologies and VMware (e.g., VMware Cloud Foundation on Dell EMC VxRail API Reference Guide and Dell EMC VxRail API Cookbook).

Base URL: https://<vxrail-manager-ip>/rest/vxm/v<version>/ (e.g., /v1/ or latest version like /v3/; check your VxRail Manager version).

API Versions: Commonly v1, v2, v3. Use the latest supported by your system (e.g., 7.x+ supports v3).

Security Note: Always use HTTPS. Avoid plaintext credentials; use secure token management. This cheatsheet uses placeholders for sensitive data.

Authentication

• Basic Authentication: Use username and password.
  • Header: Authorization: Basic <base64(username:password)>
• Token-based (Preferred for automation):
  • POST to /system/auth/login with JSON body: {\"username\": \"<user>\", \"password\": \"<pass>\"}
  • Response: {\"token\": \"<jwt-token>\"}
  • Use in headers: Authorization: Bearer <token>
• Session Management: Tokens expire; refresh as needed.
• Best Practice: Use API keys or OAuth where possible; store securely (e.g., via environment variables).

Common Endpoints and Methods

System Information

• Get System Health: GET /system/health

  • Params: None
  • Response: JSON with cluster health status.

• Get System Info: GET /system

  • Response: System details like version, build.

Cluster Management

• Get Cluster Details: GET /cluster

  • Response: Cluster config, nodes, status.

• Shutdown Cluster: POST /cluster/shutdown

  • Body: JSON with confirmation params.

• Expand Cluster: POST /lifecycle/expansion

  • Body: JSON with node specs (e.g., {"nodes": [...]})
  • Requires validation first via /lifecycle/expansion/validate.

Hosts and Nodes

• List Hosts: GET /hosts

  • Response: Array of host objects with ID, status, firmware.

• Get Host Details: GET /hosts/<host-id>

  • Response: Detailed host info.

• Power On/Off Host: POST /hosts/<host-id>/power/<action> (action: on/off)

Lifecycle and Upgrades

• Get Upgrade History: GET /lifecycle/upgrades

  • Response: List of past upgrades.

• Check for Updates: GET /lifecycle/updates

  • Response: Available bundles.

• Perform Upgrade: POST /lifecycle/upgrades

  • Body: JSON with bundle ID and options.

Monitoring and Support

• Get Logs: GET /support/logs

  • Params: ?type= (e.g., system, audit)

• Generate Support Bundle: POST /support/logs/bundle

  • Body: JSON with scope.

Example Requests (using curl)

Authenticate and Get Token

curl -k -X POST \"https://<vxm-ip>/rest/vxm/v1/system/auth/login\" \
  -H \"Content-Type: application/json\" \
  -d '{\"username\": \"<user>\", \"password\": \"<pass>\"}'

Get System Health (with Token)

curl -k -X GET \"https://<vxm-ip>/rest/vxm/v1/system/health\" \
  -H \"Authorization: Bearer <token>\"

List Hosts

curl -k -X GET \"https://<vxm-ip>/rest/vxm/v1/hosts\" \
  -H \"Authorization: Bearer <token>\"

Error Handling

• Common Codes: 401 (Unauthorized), 404 (Not Found), 500 (Internal Error).
• Responses include "error_code" and "message".

Tips

• Rate Limiting: Not officially documented; monitor for throttling.
• Tools: Use Postman for testing (import collections from Dell's GitHub).
• Documentation Sources:
  • Official API Reference: https://developer.broadcom.com/xapis/vmware-cloud-foundation-for-vxrail-api/latest/
  • Dell TechCenter: https://www.dell.com/support/home/en-us/product-support/product/vxrail-series/drivers
  • Blog Examples: https://www.pramodrane.com/restful-api-for-dellemc-vxrail-via-postman/
• Version Compatibility: APIs may vary by VxRail release (e.g., 7.0+ has enhanced lifecycle endpoints).
• Secure Practices: Use HTTPS, rotate tokens, least privilege access.

Last updated: 2025-08-09. Verify with your VxRail version for changes. "