diff --git a/source/content/guides/secrets/01-introduction.md b/source/content/guides/secrets/01-introduction.md index 79cff545a7..a1b58b38fd 100644 --- a/source/content/guides/secrets/01-introduction.md +++ b/source/content/guides/secrets/01-introduction.md @@ -1,27 +1,23 @@ --- -title: Terminus Plugins: -subtitle: Terminus Secrets Manager Plugin +title: Pantheon Secrets Guide +subtitle: Introduction description: Securely store secrets in the Pantheon Platform. terminuspage: true type: terminuspage layout: terminuspage -contributors: [whitneymeredith] +contributors: [stovak] contenttype: [guide] innav: [true] -categories: [cli] +categories: [secrets] cms: [drupal, wordpress] audience: [development] -product: [terminus] +product: [secrets] integration: [--] tags: [reference, cli, local, terminus, workflow] -permalink: docs/terminus +permalink: docs/guides/secrets/introduction reviewed: "2024-05-01" --- -# Pantheon Secrets - -## Introduction - Pantheon Secrets is key to maintaining industry best practices for secure builds and application implementation. This feature provides a convenient mechanism for you to manage your secrets and API keys directly on the Pantheon platform. This guide covers features and use cases of the Pantheon Secrets feature; it could also be referred as Secrets Manager because that is the Terminus plugin name. Features @@ -36,113 +32,13 @@ Community submitted bugs and feature requests can be found in the plugin, SDK or [Contact Support](https://dashboard.pantheon.io/#support/support/all) if you have questions or need help with Terminus. -### Contribute to Pantheon Secrets +## Contribute to Pantheon Secrets The plugin, sdk or Drupal module are open source. You can view the projects and contribute, file issues and submit feature requests. -### More Resources +## More Resources * [Terminus Plugin GitHub Repository](https://github.com/pantheon-systems/terminus-secrets-manager-plugin) * [PHP SDK GitHub repository](https://github.com/pantheon-systems/customer-secrets-php-sdk) * [Drupal module GitHub repository](https://github.com/pantheon-systems/pantheon_secrets) * [Drupal module](https://www.drupal.org/project/pantheon_secrets) - -## - - - - - - - -Terminus Plugin -Introduction -Installation -Refer to https://docs.pantheon.io/terminus/plugins[e] ? -Site Secrets Commands -Organization Secrets Commands[f][g] -Help -`terminus list secret` -Github issue queue -Community slack? - - -Use Case: Using secrets with Integrated Composer -Introduction -Mechanism 1: Oauth composer authentication (recommended) -GitHub -GitLab -Bitbucket -Mechanism 2: HTTP Basic Authentication -TEST THAT WHAT IS IN THE PLUGIN STILL WORKS! -Use Case: Using secrets with Drupal Key module[h] -https://github.com/pantheon-systems/pantheon_secrets/blob/1.0.x/docs/example.md - - -Also short version in README: https://github.com/pantheon-systems/pantheon_secrets/blob/1.0.x/README.md#usage - - -Use Case: Accessing secrets from your codebase -Introduction -Include this note: "Note: Only get has been implemented so far. You should handle your secrets through terminus using Terminus Secrets Manager." Do not present this as something we "may" do in the future! - - -Also: https://github.com/pantheon-systems/customer-secrets-php-sdk?tab=readme-ov-file#restrictions - - -Note: this also applies to quicksilver scripts -Mechanism 1: get_pantheon_secrets -Mechanism 2: OOP (get a better name here!!![i][j]) -https://github.com/pantheon-systems/customer-secrets-php-sdk?tab=readme-ov-file#usage - - -Resources -See our detailed Drupal or WordPress examples for more detailed end to end examples. - - -Pantheon Secrets and local development environments -Introduction -Your local dev env won't ever be able to talk directly to secrets service so you need workarounds!! (THIS IS NOT REAL DOCS TEXT) - - -Document this: https://github.com/pantheon-systems/customer-secrets-php-sdk?tab=readme-ov-file#local-environment-usage - - -Troubleshooting -Integrated Composer Build fails on private packages -Start with https://getpantheon.atlassian.net/wiki/spaces/CS/pages/2703294468/IC+Build+fails+on+private+packages and make it user friendly - - -Errors setting or deleting secrets -https://getpantheon.atlassian.net/wiki/spaces/CS/pages/2703163413/Errors+setting+or+deleting+secrets - - - - -Rate limiting -https://github.com/pantheon-systems/terminus-secrets-manager-plugin?tab=readme-ov-file#rate-limiting - - -Still having issues? -Contact support -What about open source projects? I (Kevin) still think it's better to go through support but unsureā€¦ - - -[a]Page ready for review -[b]Not sure of better wording for this but agree with this as a page -[c]Yeah, happy to rename it if anyone has suggestions -[d]just a note that we should be careful to qualify what works here. we've had people ask for methods that aren't supported... iirc one was "a single secret for all multidevs, but different from dev" -1 total reaction -Kevin Porras reacted with šŸ‘ at 2024-04-19 10:57 AM -[e]since the actual plugin installation is a single command, i'd list the first step as being on the latest version of terminus and link to terminus install doc there.. then i'd put the literal `terminus plugin:install` command in a code box for quick copy/paste. can still link to plugins docu if desired. -[f]Also need a section for env overrides (for both site secrets and org secrets) -[g]I added env overrides as a concept in the previous page and will of course mention them in both site and org secrets. - - -Env overrides are not a command by themselves but options in the commands -[h]My intuition is that this should come after the "Accessing secrets from your codebase". I think the latter will probably be the more common use case, and isn't CMS-specific. - - -But I don't feel strongly about it -[i]POOP -[j]j/k. This is the composer package, right? `get_pantheon_secrets` isn't the composer package? If that's right, then I'd say "composer package" or "composer library"? \ No newline at end of file diff --git a/source/content/guides/secrets/02-basic-concepts.md b/source/content/guides/secrets/02-basic-concepts.md index 24ea116e63..bd74cfa92b 100644 --- a/source/content/guides/secrets/02-basic-concepts.md +++ b/source/content/guides/secrets/02-basic-concepts.md @@ -1,33 +1,28 @@ --- -title: Terminus Plugins: -subtitle: Terminus Secrets Manager Plugin -description: Securely store secrets in the Pantheon Platform. +title: Pantheon Secrets Guide +subtitle: Basic Concepts +description: This section outlines some concepts that are worth knowing about Pantheon Secrets. Gaining familiarity with them will help you to make better use of this feature. terminuspage: true type: terminuspage layout: terminuspage -contributors: [whitneymeredith] +contributors: [stovak] contenttype: [guide] innav: [true] -categories: [cli] +categories: [secrets] cms: [drupal, wordpress] audience: [development] -product: [terminus] +product: [secrets] integration: [--] tags: [reference, cli, local, terminus, workflow] -permalink: docs/terminus +permalink: docs/guides/secrets/basic-concepts reviewed: "2024-05-01" --- +
+
Secret
+
A key-value pair that should not be exposed to the general public, typically something like a password, API key, or other sensitive information that you should probably not add to version control.
-# Basic Concepts - - This section outlines some concepts that are worth knowing about Pantheon Secrets. Gaining familiarity with them will help you to make better use of this feature. - -## Secret - - A key-value pair that should not be exposed to the general public, typically something like a password, API key, or other sensitive information that you should probably not add to version control. - -## Secret type [^1] - +
Secret type [^1]
+
This is a field on the secret record. It defines the usage for this secret and how it is consumed. Current types are: * runtime: this secret will be used to retrieve it in application runtime using API calls to the secret service. This is the recommended type to set if you want your secret to be exposed to the application runtime. @@ -35,11 +30,10 @@ reviewed: "2024-05-01" * env: this secret will be used to set environment variables in the application runtime. This type is currently only supported for Integrated Composer builds and not being exposed as environment variables to the application runtime. * composer: this secret type is used for composer authentication to private packages and it is the recommended method for doing so. +
-[^1]: Note that you can only set one type per secret and this cannot be changed later (unless you delete and recreate the secret). - -## Secret scope - +
Secret Scope
+
A secret's scope is the answer to the question "Where is the secret's value available?" * `runtime`: this secret will be used to retrieve it in application runtime using API calls to the secret service. This is the recommended type to set if you want your secret to be exposed to the application runtime. @@ -47,18 +41,23 @@ A secret's scope is the answer to the question "Where is the secret's value avai * `env`: this secret will be used to set environment variables in the application runtime. This type is currently only supported for Integrated Composer builds and not being exposed as environment variables to the application runtime. * `composer`: this secret type is used for composer authentication to private packages and it is the recommended method for doing so. +
-## Owning Entity - +
Owning Entity
+
* **Organization-owned secrets** - Organization-owned secrets are available to every site and environment that are associated with the owning organization. A common use-cases is for a CI system and infrastructure that's shared among all sites in an organization. * **Site-owned secrets** - Site-owned secrets are available to the site and all of it's environments. A common use-case is Github tokens that a site's composer build can use to access private repos referenced in the composer file. * **Environment override**[^d] - Environment overrides provide overrides to a secret value for a specific environment. A common use case for this are API keys that are different in production and non-production environments. +
-## Value Resolution - +
Value Resolution
+
1. Organization values are resolved first. They form the base value for the key-pair's value resolution. 2. Site values are resolved second and secret values set on the site level will override secret values set for the organization. To return the secret to it's organization value, simply delete the site value. 3. Environmental overrides are resolved finally and if the override exists, it will become the value provided to the calling function. +
+
+[^1]: Note that you can only set one type per secret and this cannot be changed later (unless you delete and recreate the secret). diff --git a/source/content/guides/secrets/03-terminus-plugin.md b/source/content/guides/secrets/03-terminus-plugin.md new file mode 100644 index 0000000000..5eef81583c --- /dev/null +++ b/source/content/guides/secrets/03-terminus-plugin.md @@ -0,0 +1,40 @@ +--- +title: Pantheon Secrets Guide +subtitle: Terminus Secrets Manager Plugin +description: Terminus plugin for Pantheon Secrets +terminuspage: true +type: terminuspage +layout: terminuspage +contributors: [stovak] +contenttype: [guide] +innav: [true] +categories: [secrets] +cms: [drupal, wordpress] +audience: [development] +product: [secrets] +integration: [--] +tags: [reference, cli, local, terminus, workflow] +permalink: docs/guides/secrets/terminus-plugin +reviewed: "2024-05-01" +--- + + +https://github.com/pantheon-systems/terminus-secrets-manager-plugin + +## Introduction + +## Installation + +Refer to [https://docs.pantheon.io/terminus/plugins](https://docs.pantheon.io/terminus/plugins) ? + +## Site Secrets Commands + +## Organization Secrets Commands + +## Help + +`terminus list secret` + +Github issue queue + +Community slack? diff --git a/source/content/guides/secrets/04-use-cases.md b/source/content/guides/secrets/04-use-cases.md new file mode 100644 index 0000000000..c8d690d1eb --- /dev/null +++ b/source/content/guides/secrets/04-use-cases.md @@ -0,0 +1,62 @@ +--- +title: Pantheon Secrets Guide +subtitle: Use Cases +description: Some common uses cases for Pantheon Secrets +terminuspage: true +type: terminuspage +layout: terminuspage +contributors: [stovak] +contenttype: [guide] +innav: [true] +categories: [secrets] +cms: [drupal, wordpress] +audience: [development] +product: [secrets] +integration: [--] +tags: [reference, cli, local, terminus, workflow] +permalink: docs/guides/secrets/use-cases +reviewed: "2024-05-01" +--- + +# Use Case: Using secrets with Integrated Composer + +## Introduction + +## Mechanism 1: Oauth composer authentication (recommended) + +### GitHub + +### GitLab + +### Bitbucket + +## Mechanism 2: HTTP Basic Authentication + +TEST THAT WHAT IS IN THE PLUGIN STILL WORKS! + +# Use Case: Using secrets with Drupal Key module + +[https://github.com/pantheon-systems/pantheon_secrets/blob/1.0.x/docs/example.md](https://github.com/pantheon-systems/pantheon_secrets/blob/1.0.x/docs/example.md) + +Also short version in README: [https://github.com/pantheon-systems/pantheon_secrets/blob/1.0.x/README.md#usage](https://github.com/pantheon-systems/pantheon_secrets/blob/1.0.x/README.md#usage) + +# Use Case: Accessing secrets from your codebase + +### Introduction + +Include this note: "Note: Only get has been implemented so far. You should handle your secrets through terminus using [Terminus Secrets Manager](https://github.com/pantheon-systems/terminus-secrets-manager-plugin)." Do not present this as something we "may" do in the future! + +Also: [https://github.com/pantheon-systems/customer-secrets-php-sdk?tab=readme-ov-file#restrictions](https://github.com/pantheon-systems/customer-secrets-php-sdk?tab=readme-ov-file#restrictions) + +Note: this also applies to quicksilver scripts + +## Mechanism 1: get_pantheon_secrets + +## Mechanism 2: OOP (get a better name here!!!) + +[https://github.com/pantheon-systems/customer-secrets-php-sdk?tab=readme-ov-file#usage](https://github.com/pantheon-systems/customer-secrets-php-sdk?tab=readme-ov-file#usage) + +## Resources + +See our detailed [Drupal](https://github.com/pantheon-systems/customer-secrets-php-sdk/blob/main/docs/drupal-example.md) or [WordPress](https://github.com/pantheon-systems/customer-secrets-php-sdk/blob/main/docs/wordpress-example.md) examples for more detailed end to end examples. + diff --git a/source/content/guides/secrets/05-local-development.md b/source/content/guides/secrets/05-local-development.md new file mode 100644 index 0000000000..47ffb918ca --- /dev/null +++ b/source/content/guides/secrets/05-local-development.md @@ -0,0 +1,26 @@ +--- +title: Pantheon Secrets Guide +subtitle: Terminus Secrets Manager Plugin +description: Securely store secrets in the Pantheon Platform. +terminuspage: true +type: terminuspage +layout: terminuspage +contributors: [stovak] +contenttype: [guide] +innav: [true] +categories: [secrets] +cms: [drupal, wordpress] +audience: [development] +product: [secrets] +integration: [--] +tags: [reference, cli, local, terminus, workflow] +permalink: docs/guides/secrets/local-development +reviewed: "2024-05-01" +--- +# Pantheon Secrets and local development environments + +## Introduction + +Your local dev env won't ever be able to talk directly to secrets service so you need workarounds!! (THIS IS NOT REAL DOCS TEXT) + +Document this: [https://github.com/pantheon-systems/customer-secrets-php-sdk?tab=readme-ov-file#local-environment-usage](https://github.com/pantheon-systems/customer-secrets-php-sdk?tab=readme-ov-file#local-environment-usage)** \ No newline at end of file diff --git a/source/content/guides/secrets/06-troubleshooting.md b/source/content/guides/secrets/06-troubleshooting.md new file mode 100644 index 0000000000..b850198ac3 --- /dev/null +++ b/source/content/guides/secrets/06-troubleshooting.md @@ -0,0 +1,40 @@ +--- +title: Pantheon Secrets Guide +subtitle: Terminus Secrets Manager Plugin +description: Securely store secrets in the Pantheon Platform. +terminuspage: true +type: terminuspage +layout: terminuspage +contributors: [stovak] +contenttype: [guide] +innav: [true] +categories: [secrets] +cms: [drupal, wordpress] +audience: [development] +product: [secrets] +integration: [--] +tags: [reference, cli, local, terminus, workflow] +permalink: docs/guides/secrets/troubleshooting +reviewed: "2024-05-01" +--- +# Troubleshooting + +## Integrated Composer Build fails on private packages + +Start with [https://getpantheon.atlassian.net/wiki/spaces/CS/pages/2703294468/IC+Build+fails+on+private+packages](https://getpantheon.atlassian.net/wiki/spaces/CS/pages/2703294468/IC+Build+fails+on+private+packages) and make it user friendly + +## Errors setting or deleting secrets + +[https://getpantheon.atlassian.net/wiki/spaces/CS/pages/2703163413/Errors+setting+or+deleting+secrets](https://getpantheon.atlassian.net/wiki/spaces/CS/pages/2703163413/Errors+setting+or+deleting+secrets) + +## Rate limiting + +[https://github.com/pantheon-systems/terminus-secrets-manager-plugin?tab=readme-ov-file#rate-limiting](https://github.com/pantheon-systems/terminus-secrets-manager-plugin?tab=readme-ov-file#rate-limiting) + +## Still having issues? + +Contact support + +What about open source projects? I (Kevin) still think it's better to go through support but unsureā€¦ + +** \ No newline at end of file