Skip to content

Commit

Permalink
building out the guide
Browse files Browse the repository at this point in the history
  • Loading branch information
@stovak
stovak committed May 1, 2024
1 parent 2f46a9a commit 60b5304
Show file tree
Hide file tree
Showing 6 changed files with 200 additions and 137 deletions.
120 changes: 8 additions & 112 deletions source/content/guides/secrets/01-introduction.md
View file
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -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"?
49 changes: 24 additions & 25 deletions source/content/guides/secrets/02-basic-concepts.md
View file
Original file line number Diff line number Diff line change
@@ -1,64 +1,63 @@
---
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"
---
<dl>
<dt>Secret</dt>
<dd>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.</dd>

# 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]

<dt>Secret type [^1]</dt>
<dd>
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.

* 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.
</dd>

[^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

<dt>Secret Scope</dt>
<dd>
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.

* `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.
</dd>

## Owning Entity

<dt>Owning Entity</dt>
<dd>
* **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.
</dd>

## Value Resolution

<dt>Value Resolution</dt>
<dd>
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.
</dd>
</dl>

[^1]: Note that you can only set one type per secret and this cannot be changed later (unless you delete and recreate the secret).
40 changes: 40 additions & 0 deletions source/content/guides/secrets/03-terminus-plugin.md
View file
Original file line number Diff line number Diff line change
@@ -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?
62 changes: 62 additions & 0 deletions source/content/guides/secrets/04-use-cases.md
View file
Original file line number Diff line number Diff line change
@@ -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.

26 changes: 26 additions & 0 deletions source/content/guides/secrets/05-local-development.md
View file
Original file line number Diff line number Diff line change
@@ -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)**
Loading

0 comments on commit 60b5304

Please sign in to comment.