diff --git a/.wordlist.txt b/.wordlist.txt index 53ba97434..43c5b26ea 100644 --- a/.wordlist.txt +++ b/.wordlist.txt @@ -585,6 +585,7 @@ MyExtension MyPlugin MyTestClass MyTestInterface +NATS NPM NUR NVDA diff --git a/products/paas/shopware/guides/secrets-vault-guide.md b/products/paas/shopware/guides/secrets-vault-guide.md index cdfb66f3a..8f1701d6e 100644 --- a/products/paas/shopware/guides/secrets-vault-guide.md +++ b/products/paas/shopware/guides/secrets-vault-guide.md @@ -101,3 +101,213 @@ sw-paas vault get --secret-id ssh-abc123xyz ```sh sw-paas vault delete --secret-id ssh-abc123xyz ``` + +## Default Secrets & Ownership + +The Shopware PaaS Vault contains both system-managed and user-managed secrets. Understanding the difference helps you identify which secrets you can manage and which are maintained by the platform. + +### System-Managed vs. User-Managed Secrets + +**System-managed secrets** are automatically created and maintained by Shopware PaaS for internal operations. While these secrets are visible when you run `sw-paas vault list`, they should not be modified or deleted as they are critical for platform functionality. + +**User-managed secrets** are created by you for your application's specific needs, such as API tokens, database credentials, or SSH keys for private repositories. + +### Common Secrets Reference + +| Secret Name | Description | Managed By | Editable by User | Notes | +|-------------|-------------|------------|------------------|-------| +| `STOREFRONT_CREDENTIALS` | Internal storefront credentials | System | No | **Do not delete** - Required for storefront functionality | +| `GRAFANA_CREDENTIALS` | Grafana dashboard login credentials | System | No | **Do not delete** - Needed for `sw-paas open grafana` | +| `NATS_USER_CREDENTIALS` | NATS messaging user credentials | System | No | **Do not delete** - Required for internal messaging | +| `STOREFRONT_PROXY_KEY` | Storefront proxy authentication | System | No | **Do not delete** - Required for routing | +| `SSH_PRIVATE_KEY` | Deploy SSH key for repository access | User | Yes | See [SSH key workflow](#example-workflow-using-ssh-keys) | +| `SHOPWARE_PACKAGES_TOKEN` | Token for accessing Shopware packages | User | Yes | Watch for typo variants (e.g. missing underscore: `SHOPWAREPACKAGES_TOKEN`) | + +::: info +System-managed secrets use the same retrieval mechanism as user-managed secrets, which is why they appear in your vault list. This is intentional to provide transparency into the credentials your environment is using. +::: + +### Filtering Secrets by Application + +By default, `sw-paas vault list` shows secrets across all applications in your organization, which can lead to duplicate entries if multiple apps use the same secret names. + +To view secrets for a specific application: + +```sh +sw-paas vault list --application-id YOUR-APP-ID +``` + +To find your application ID: + +```sh +sw-paas application list +``` + +## Permissions & Behavior + +::: danger +**Do not delete system-managed secrets.** Deleting secrets like `STOREFRONT_CREDENTIALS`, `GRAFANA_CREDENTIALS`, `NATS_USER_CREDENTIALS`, or `STOREFRONT_PROXY_KEY` will cause platform outages and break critical functionality. +::: + +### System-Managed Secret Restrictions + +System-managed secrets are read-only and should not be modified or deleted. They are essential for: + +- Storefront operations and routing +- Monitoring and observability (Grafana) +- Internal messaging and communication (NATS) +- Platform infrastructure + +If you believe a system-managed secret is incorrect or causing issues: + +1. **Do not delete or modify the secret** +2. Document the issue, including the secret name and observed behavior +3. Contact Shopware PaaS support immediately +4. Do not attempt to work around system secrets by creating duplicates + +### Secret History & Rollback + +::: warning Important +Shopware PaaS does not maintain version history for secrets. Once a secret is modified or deleted, the previous value cannot be recovered through the platform. +::: + +Always back up critical secret values locally before making changes: + +```sh +# Retrieve and save a secret locally before modifying +sw-paas vault get --secret-id SECRET-ID > backup-SECRET-NAME.txt +``` + +## Housekeeping & Legacy Secrets + +### Identifying Legacy or Typo Secrets + +Over time, your Vault may accumulate outdated or incorrectly-named secrets. Common issues include: + +- **Typo secrets**: e.g. `SHOPWAREPACKAGES_TOKEN` instead of `SHOPWARE_PACKAGES_TOKEN` +- **Deprecated secrets**: No longer used by current application versions +- **Duplicate secrets**: Same secret created multiple times with different IDs + +### Recommended Cleanup Process + +1. **Audit your secrets**: + + ```sh + sw-paas vault list --application-id YOUR-APP-ID + ``` + +2. **Identify unused secrets**: Review each secret and confirm whether it's actively used by your application + +3. **Back up before deletion**: + + ```sh + sw-paas vault get --secret-id SECRET-ID > backup-SECRET-NAME.txt + ``` + +4. **Delete unused secrets**: + + ```sh + sw-paas vault delete --secret-id SECRET-ID + ``` + +5. **Document the cleanup**: Keep a record of what was deleted and when for future reference + +### Dealing with Typo Secrets + +If you discover a secret with a typo in its name, you have two options: + +**Option 1: Edit the existing secret (faster)** + +1. Edit the secret to correct its name or value: + + ```sh + sw-paas vault edit + ``` + +2. Select the secret from the list and update its value as needed + +3. Update your application to use the corrected secret name if it changed + +4. Test thoroughly to ensure the updated secret works + +**Option 2: Create a new secret and delete the old one** + +1. Back up the typo secret's value: + + ```sh + sw-paas vault get --secret-id TYPO-SECRET-ID > backup-typo-SECRET-NAME.txt + ``` + +2. Create a correctly-named secret: + + ```sh + sw-paas vault create + ``` + +3. Update your application to use the correct secret + +4. Test thoroughly to ensure it works + +5. Delete the typo secret: + + ```sh + sw-paas vault delete --secret-id TYPO-SECRET-ID + ``` + +### Regular Maintenance + +Establish a periodic review process: + +- **Quarterly audit**: Review all user-managed secrets for relevance +- **Document ownership**: Maintain a record of which secrets are used by which applications + +## Safety & Recovery + +### Best Practices + +1. **Always back up before deletion**: + + ```sh + sw-paas vault get --secret-id SECRET-ID > $(date +%Y%m%d)-SECRET-NAME-backup.txt + ``` + +2. **Rotate sensitive credentials regularly** (e.g., every 90 days): + - Update API tokens and authentication credentials on a scheduled basis + - Use the `sw-paas vault edit` command to quickly update credential values + - Create new secrets and deprecate old ones for non-editable secret types + +3. **Test changes in non-production environments first** + +4. **Document secret purposes**: Add comments or maintain an external inventory + +5. **Use descriptive names**: Choose clear, consistent naming conventions for your secrets + +6. **Limit access**: Only share vault access with team members who need it + +### What to Do If You Accidentally Delete a Secret + +Since there is no built-in recovery mechanism: + +1. **Check local backups** you may have created before deletion + +2. **Review your application's configuration files** (if the secret was stored there temporarily during development) + +3. **Regenerate the secret** if it's a token or credential that can be recreated: + - For API tokens: Generate a new token from the service provider + - For SSH keys: Create a new key pair and update deployment keys + +4. **Contact support** if the deleted secret was critical and you have no backup + +### Support Escalation + +If you encounter issues that cannot be resolved with the above troubleshooting steps: + +1. **Gather information**: + - Secret name and ID + - Application ID + - Error messages or unexpected behavior + - Steps to reproduce the issue + +2. **Check system status**: Verify there are no ongoing PaaS incidents + +3. **Contact Shopware PaaS support** with the gathered information