Fix DigitalOcean API error handling and improve debugging (fixes #14829)

[dguido]

Summary

• Fixes Get regions #14829 by providing actionable error messages when DigitalOcean API calls fail
• Replaces hardcoded no_log: true with configurable algo_no_log variable
• Adds comprehensive error handling that maintains security while enabling debugging

Problem

Users reported in #14829 that DigitalOcean deployments fail with completely hidden error messages:

fatal: [localhost]: FAILED! => {"censored": "the output has been hidden due to the fact that 'no_log: true' was specified"}

This made it impossible to debug API authentication issues, rate limiting, or service outages.

Solution

This PR implements smart error handling that:

1. Uses configurable logging: Changes no_log: true to no_log: "{{ algo_no_log | default(true) }}" to respect user preferences
2. Provides specific guidance: Detects HTTP status codes and provides targeted troubleshooting steps
3. Maintains security: Never exposes API tokens, even when showing detailed errors
4. Improves discoverability: Adds clear troubleshooting instructions at the top of config.cfg

Technical Details

The fix uses Jinja2 conditionals to check _do_regions.status even when no_log is active. This allows showing helpful error messages without exposing sensitive data:

• 401 Unauthorized → Instructions to create a new API token
• 403 Forbidden → Token lacks required permissions
• 429 Too Many Requests → Rate limited, wait before retrying
• 500/502/503 → DigitalOcean service issues
• Connection failures → Network/firewall troubleshooting

Testing

1. Set algo_no_log: false in config.cfg to enable detailed debugging
2. Try deployment with an invalid token to see improved error messages
3. Verify that sensitive data (API tokens) are never exposed

Files Changed

• config.cfg: Added troubleshooting section at top for better discoverability
• roles/cloud-digitalocean/tasks/prompts.yml: Implemented smart error handling

Impact

• Immediately helps users experiencing issue Get regions #14829
• Provides a pattern that can be applied to all cloud providers
• Balances security (token protection) with usability (actionable errors)

🤖 Generated with Claude Code

Co-Authored-By: Claude [email protected]

[claude]

Claude finished @dguido's task —— View job

---

Code Review Complete ✅

I've thoroughly reviewed this PR and the changes look excellent! Here's my detailed feedback:

Todo List:

• Read and analyze the changed files
• Review security implications of logging changes
• Evaluate error handling logic and completeness
• Check for potential bugs or edge cases
• Assess code quality and project standards compliance
• Provide comprehensive feedback

---

Security Assessment ✅

Excellent security model: The implementation maintains strong security while enabling debugging:

• Token protection: API tokens remain hidden even when algo_no_log: false is set - the no_log: true remains on sensitive tasks (roles/cloud-digitalocean/tasks/prompts.yml:10,15)
• Smart conditional logging: Uses no_log: "{{ algo_no_log | default(true) }}" which correctly defaults to secure behavior
• Clear user guidance: The config.cfg warning is prominent and actionable

Code Quality Assessment ✅

Strong implementation with thoughtful design:

1. Error handling coverage (prompts.yml:29-79): Comprehensive HTTP status code handling:

   • 401: Clear token regeneration instructions
   • 403: Permission-specific guidance
   • 429: Rate limiting with wait advice
   • 500/502/503: Service outage detection
   • Connection failures: Network troubleshooting steps

2. Jinja2 template logic (prompts.yml:32-76): Clean conditional structure using proper elif chains

3. User experience: The troubleshooting section at the top of config.cfg (config.cfg:3-11) is perfectly placed for discoverability

Potential Issues & Suggestions 🔍

Minor improvements to consider:

1. Edge case handling: The when: _do_regions.status != 200 condition (prompts.yml:79) might not catch all failure modes. Consider checking if _do_regions.json exists before accessing it on line 83.

2. Error message consistency: The catch-all case (prompts.yml:70-76) could include the actual HTTP status code if available for better debugging.

Performance Considerations ✅

• Minimal overhead: The conditional logging adds negligible performance impact
• Fail-fast behavior: API errors are caught early in the deployment process
• No additional API calls: Uses existing regions endpoint for validation

Test Coverage Considerations 📋

Areas that could benefit from testing:

1. Template rendering: Consider adding unit tests for the Jinja2 conditionals in prompts.yml:32-76
2. Config validation: Test that algo_no_log variable behaves correctly in both true/false states
3. Error scenarios: Mock different HTTP status codes to verify error message accuracy

Code Standards Compliance ✅

• Ansible best practices: Proper use of failed_when: false and conditional failure
• YAML formatting: Clean indentation and structure
• Documentation: Excellent inline comments and user guidance
• Naming conventions: Clear, descriptive variable names (_do_regions, algo_no_log)

Overall Assessment 🎯

This is an excellent solution that elegantly solves the original issue (#14829). The implementation:

• ✅ Maintains security by default
• ✅ Provides actionable error messages for common failure scenarios
• ✅ Includes clear user documentation and troubleshooting guidance
• ✅ Follows project conventions and Ansible best practices
• ✅ Has minimal performance impact

Recommendation: This PR is ready to merge. The code quality is high, security considerations are well-handled, and it provides significant value to users experiencing API errors.

The only minor suggestion is to add error handling around _do_regions.json access to prevent potential undefined variable issues in edge cases.

---