Cloud Secret Manager Laravel Package

Getting Started

Minimal Setup

1. Install the package:

   composer require google/cloud-secret-manager
   

2. Authenticate (choose one):

   • Service Account Key (local/dev):

     putenv('GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json');
     

   • Workload Identity Federation (GCP environments): Configure IAM roles for your GCP service account.
   • Application Default Credentials (Cloud Run/GKE): Automatically picks up credentials from metadata server.

3. First use case: Fetch a secret in Laravel’s AppServiceProvider:

   use Google\Cloud\SecretManager\V1\SecretManagerServiceClient;
   use Google\Cloud\SecretManager\V1\GetSecretRequest;
   
   public function boot()
   {
       $client = new SecretManagerServiceClient();
       $request = (new GetSecretRequest())
           ->setName('projects/YOUR_PROJECT/secrets/YOUR_SECRET/versions/latest');
   
       $secret = $client->getSecret($request);
       $payload = $secret->getPayload()->getData();
   
       config(['services.database.password' => $payload]);
   }
   

Where to Look First

• API Reference for method signatures.
• Authentication Guide for GCP auth setups.
• Resource Name Helpers for constructing secret paths (e.g., SecretManagerServiceClient::secretName()).

Implementation Patterns

Core Workflows

1. Fetching Secrets Dynamically

• Use case: Replace Laravel’s env() with runtime secret fetching.
• Pattern:

  $client = new SecretManagerServiceClient();
  $secret = $client->accessSecretVersion(
      $client->secretVersionName('projects/PROJECT/secrets/DB_PASSWORD')
  );
  return $secret->getPayload()->getData();
  

• Laravel Integration:

  // app/Providers/AppServiceProvider.php
  public function register()
  {
      $this->app->bind('db.password', function () {
          return app(SecretManagerServiceClient::class)
              ->accessSecretVersion('projects/.../secrets/DB_PASSWORD')
              ->getPayload()
              ->getData();
      });
  }
  

2. Tag-Based Secret Selection

• Use case: Multi-environment or tenant-specific configs.
• Pattern:

  $filter = 'tags.environment="production" AND tags.tenant="acme"';
  $listRequest = (new ListSecretsRequest())
      ->setParent('projects/PROJECT')
      ->setFilter($filter);
  
  $secrets = $client->listSecrets($listRequest);
  foreach ($secrets as $secret) {
      // Process secrets matching tags
  }
  

3. Automated Rotation

• Use case: Rotate database passwords via Laravel scheduler.
• Pattern:

  // Rotate a secret every 30 days
  $rotation = (new AddSecretVersionRequest())
      ->setPayload((new Payload())->setData('new_password_here'))
      ->setSecretId('DB_PASSWORD');
  
  $client->addSecretVersion($rotation);
  

4. CI/CD Secret Injection

• Use case: Inject secrets into GitHub Actions without hardcoding.
• Pattern (in workflow file):

  - name: Fetch secrets
    run: |
      SECRET=$(gcloud secrets versions access latest --secret=DB_PASSWORD)
      echo "DB_PASSWORD=$SECRET" >> $GITHUB_ENV
  

• Laravel Envoyer Integration: Use Envoyer’s pre-deploy hooks to fetch secrets and inject into .env.

5. Caching Secrets

• Use case: Reduce API calls for frequently accessed secrets.
• Pattern:

  $cacheKey = 'secret:db_password';
  if (!cache()->has($cacheKey)) {
      $secret = $client->accessSecretVersion('projects/.../secrets/DB_PASSWORD');
      cache()->put($cacheKey, $secret->getPayload()->getData(), now()->addHours(1));
  }
  return cache()->get($cacheKey);
  

Integration Tips

• Laravel Config: Override configs dynamically:

  config(['services.stripe.key' => $client->accessSecretVersion('projects/.../secrets/STRIPE_KEY')->getPayload()->getData()]);
  

• Laravel Horizon: Inject Redis passwords at runtime:

  Horizon::configureUsing(function () {
      $redisPassword = $client->accessSecretVersion('projects/.../secrets/REDIS_PASSWORD')->getPayload()->getData();
      return ['redis' => ['password' => $redisPassword]];
  });
  

• Laravel Nova: Secure API keys:

  Nova::serving(function () {
      $novaKey = $client->accessSecretVersion('projects/.../secrets/NOVA_KEY')->getPayload()->getData();
      config(['nova.key' => $novaKey]);
  });
  

• Laravel Forge/Envoyer: Use post-deploy hooks to sync secrets:

  # In Envoyer post-deploy script
  gcloud secrets versions access latest --secret=APP_KEY > /var/www/.env
  

Gotchas and Tips

Pitfalls

1. Authentication Failures:

   • Issue: ApiException with 403 Permission Denied.
   • Fix: Ensure the GCP service account has roles/secretmanager.secretAccessor (or higher) and the secret’s IAM policy allows access.
   • Debug: Use GOOGLE_APPLICATION_CREDENTIALS_DEBUG=true to log auth details.

2. Resource Name Format:

   • Issue: InvalidArgumentException for malformed secret names.
   • Fix: Use the client’s helper methods:

     $name = $client->secretName('projects/PROJECT/secrets/SECRET');
     

3. Payload Decoding:

   • Issue: getData() returns binary data (not a string).
   • Fix: Decode the payload:

     $payload = base64_decode($secret->getPayload()->getData());
     

4. Rate Limiting:

   • Issue: 429 Too Many Requests during peak loads.
   • Fix: Implement exponential backoff or cache secrets aggressively.

5. Delayed Destruction:

   • Issue: Accidentally destroying secrets with destroySecret().
   • Fix: Use disableSecretVersion() for soft deletion or set a retention period:

     $request = (new DestroySecretRequest())
         ->setName('projects/PROJECT/secrets/SECRET')
         ->setForceDestroy(false); // Enables delayed destruction
     

6. PHP Version Mismatch:

   • Issue: Class not found errors on PHP <8.1.
   • Fix: Upgrade PHP or use an older package version (e.g., 1.15.x).

7. gRPC vs. REST:

   • Issue: gRPC methods not working as expected.
   • Fix: Ensure gRPC is installed:

     pecl install grpc
     

     Or fall back to REST:

     $client = new SecretManagerServiceClient(['grpc' => false]);
     

Debugging Tips

• Enable Debug Logging:

  $client = new SecretManagerServiceClient([
      'logger' => new \Google\ApiCore\Logging\Logger(
          new \Monolog\Logger('secret-manager', [new \Monolog\Handler\StreamHandler('php://stderr')])
      )
  ]);
  

• Validate Secret Names: Use the Secret Manager Resource Names guide to ensure correct formatting.
• Test Locally with Mocks:

  $mockClient = $this->createMock(SecretManagerServiceClient::class);
  $mockClient->method('accessSecretVersion')
      ->willReturn((new SecretVersion())->setPayload((new Payload())->setData('mock_password')));
  

• Check Quotas: Monitor Secret Manager quotas to avoid throttling.

Extension Points

1. Custom Secret Classes: Extend Secret or SecretVersion for domain-specific logic:

   class DatabaseSecret extends Secret
   {
       public function getHost(): string
       {
           return $this->getMetadata()['host'] ?? '';
       }
   }
   

2. Event Listeners: Trigger actions on secret updates (e.g., restart workers):

   $client->addSecretVersion($request)->wait();
   // Dispatch event to