Openstack Laravel Package

## Getting Started

### Minimal Setup
1. **Install the package**:
   ```bash
   composer require php-opencloud/openstack

2. Configure credentials (via environment variables or config file):

   use OpenStack\OpenStack;
   
   $connection = OpenStack::connection([
       'region' => 'RegionOne',
       'auth' => [
           'authUrl' => 'https://keystone.example.com:5000/v3',
           'username' => 'your-username',
           'password' => 'your-password',
           'project' => 'your-project',
           'userDomainName' => 'Default',
           'projectDomainName' => 'Default',
       ],
   ]);
   

3. First use case: List servers (Compute):

   $servers = $connection->compute()->servers()->all();
   foreach ($servers as $server) {
       echo $server->name . "\n";
   }
   

Where to Look First

• Documentation: Official Docs
• Samples: /samples/ directory for real-world examples (e.g., samples/compute/create_server.php).
• Service Coverage: Check /COVERAGE.md for supported OpenStack services/versions (e.g., Nova, Cinder, Swift).
• API Reference: Service-specific Api.php files (e.g., src/Compute/v2/Api.php) for operation details.

Implementation Patterns

Core Workflows

1. Service Initialization

• Pattern: Use OpenStack::connection() with a config array or ConnectionInterface implementation.
• Example:

  $connection = OpenStack::connection([
      'region' => 'RegionOne',
      'auth' => ['authUrl' => '...', 'username' => '...', ...],
  ]);
  

• Tip: Store credentials in Laravel’s .env and use config('services.openstack').

2. Resource Operations

• Pattern: Chain service methods (e.g., compute()->servers()) and use fluent interfaces.
• Example:

  // Create a server
  $server = $connection->compute()->servers()->create([
      'name' => 'web-server',
      'imageRef' => 'ubuntu-22.04',
      'flavorRef' => 'm1.small',
      'networks' => [['uuid' => 'net-uuid']],
  ]);
  
  // List servers with pagination
  $servers = $connection->compute()->servers()->all();
  foreach ($servers as $server) {
      echo $server->id . ": " . $server->status . "\n";
  }
  

3. Large Object Handling (Swift)

• Pattern: Use createLargeObject() for files >10GB with customizable segment indexing.
• Example:

  $container = $connection->objectStore()->containers()->find('my-container');
  $largeObject = $container->createLargeObject('huge-file.dat', [
      'segmentIndexFormat' => 'custom-{index}.part',
  ]);
  $largeObject->uploadFromFile('/path/to/huge-file.dat');
  

4. Async Operations with Waiters

• Pattern: Use HasWaiterTrait (e.g., Compute::Image) for long-running tasks.
• Example:

  $image = $connection->compute()->images()->find('image-uuid');
  $image->waitFor('active');
  

5. Error Handling

• Pattern: Catch OpenStack\Common\Exception\ServiceException and use errorVerbosity for debugging.
• Example:

  try {
      $server->delete();
  } catch (ServiceException $e) {
      if ($e->getErrorVerbosity() === ServiceException::VERBOSITY_DEBUG) {
          echo $e->getDebugInfo();
      }
  }
  

6. Authentication Flexibility

• Pattern: Use applicationCredentials or Token::validate() for zero-trust workflows.
• Example:

  // Application credentials
  $connection = OpenStack::connection([
      'auth' => [
          'authUrl' => '...',
          'applicationCredentialId' => 'cred-uuid',
          'applicationCredentialSecret' => 'secret',
      ],
  ]);
  
  // Token validation
  $token = $connection->identity()->tokens()->find('token-uuid');
  if ($token->validate()) {
      // Proceed
  }
  

Laravel Integration Tips

1. Service Provider:

   use OpenStack\OpenStack;
   
   class OpenStackServiceProvider extends ServiceProvider {
       public function register() {
           $this->app->singleton('openstack', function ($app) {
               return OpenStack::connection(config('services.openstack'));
           });
       }
   }
   

2. Facade:

   // app/Facades/OpenStack.php
   namespace App\Facades;
   
   use Illuminate\Support\Facades\Facade;
   
   class OpenStack extends Facade {
       protected static function getFacadeAccessor() {
           return 'openstack';
       }
   }
   

3. Config:

   // config/services.php
   'openstack' => [
       'region' => env('OPENSTACK_REGION'),
       'auth' => [
           'authUrl' => env('OPENSTACK_AUTH_URL'),
           'username' => env('OPENSTACK_USERNAME'),
           'password' => env('OPENSTACK_PASSWORD'),
           'project' => env('OPENSTACK_PROJECT'),
       ],
   ],
   

Gotchas and Tips

Pitfalls

1. Deprecated Keystone v2:

   • The SDK drops support for Keystone v2 in v3.10+. Ensure your OpenStack cluster uses v3.
   • Fix: Update authUrl to include /v3 (e.g., https://keystone.example.com/v3).

2. Token Expiry:

   • Tokens expire after ~1 hour. Use Token::validate() or handle 401 Unauthorized errors gracefully.
   • Tip: Implement a middleware to refresh tokens:

     $connection->identity()->tokens()->refresh();
     

3. Large Object Segments:

   • Default segment naming (segment-{index}) may conflict with existing files.
   • Fix: Customize segmentIndexFormat (e.g., custom-{index}.part).

4. Case-Sensitive Headers (Swift):

   • Metadata headers in Swift are case-insensitive (fixed in v3.10).
   • Tip: Use X-Object-Meta-* consistently.

5. Guzzle Promises:

   • The SDK uses GuzzleHttp\Promise\Utils::all (not GuzzleHttp\Promise\all).
   • Fix: Ensure guzzlehttp/promises>=2.0 is installed.

6. Server Groups (Nova):

   • Server groups require affinity policies (e.g., soft-anti-affinity).
   • Tip: Check Compute::ServerGroup::create() for policy constraints.

Debugging Tips

1. Enable Verbose Errors:

   $connection->setErrorVerbosity(OpenStack\Common\Exception\ServiceException::VERBOSITY_DEBUG);
   

2. Log Raw Responses:
   • Use Guzzle middleware to log requests/responses:

     $stack = HandlerStack::create();
     $stack->push(Middleware::tap(function ($request) {
         \Log::debug('Request:', ['url' => (string) $request->getUri(), 'body' => $request->getBody()]);
     }));
     $connection->setHandler($stack);
     

3. Check Headers:
   • Invalid headers (e.g., Content-Type) can cause silent failures. Validate with:

     $request->getHeaders();
     

Extension Points

1. Custom Models:
   • Extend OpenStack\Common\Resource\OperatorResource to add behavior:

     class CustomServer extends \OpenStack\Compute\v2\Models\Server {
         public function customAction() {
             return $this->execute('POST', '/servers/{id}/action', ['os-custom-action' => true]);
         }
     }
     

2. Middleware:
   • Add custom Guzzle middleware for logging, retries, or auth:

     $connection->setHandler(HandlerStack::create([
         new Middleware(),
         $connection->getHandler(),
     ]));
     

3. Service Extensions:
   • Implement missing APIs by extending OpenStack\Common\Service:

     class CustomService extends \OpenStack\Common\Service {
         public function customMethod() {
             return $this->execute('GET', '/custom-endpoint');
         }
     }
     

4. Pagination:
   • Override enumerate() in models for custom pagination:

     public function enumerate($limit =