mirror of
https://github.com/hashicorp/vault-action.git
synced 2025-11-14 18:13:45 +00:00
Update doc
This commit is contained in:
parent
622329f2ef
commit
2eff75fabd
2 changed files with 19 additions and 93 deletions
110
README.md
110
README.md
|
|
@ -4,18 +4,10 @@
|
||||||
|
|
||||||
**Please note**: We take Vault's security and our users' trust very seriously. If you believe you have found a security issue in Vault or this Vault Action, _please responsibly disclose_ by contacting us at [security@hashicorp.com](mailto:security@hashicorp.com).
|
**Please note**: We take Vault's security and our users' trust very seriously. If you believe you have found a security issue in Vault or this Vault Action, _please responsibly disclose_ by contacting us at [security@hashicorp.com](mailto:security@hashicorp.com).
|
||||||
|
|
||||||
This repository was recently adopted by HashiCorp. We're actively working on adding
|
|
||||||
additional functionality to this action soon:
|
|
||||||
|
|
||||||
- [ ] TLS
|
|
||||||
- [ ] mTLS
|
|
||||||
- [ ] Simplify secret request UX
|
|
||||||
---
|
---
|
||||||
|
|
||||||
A helper action for easily pulling secrets from HashiCorp Vault™.
|
A helper action for easily pulling secrets from HashiCorp Vault™.
|
||||||
|
|
||||||
By default, this action pulls from [Version 2](https://www.vaultproject.io/docs/secrets/kv/kv-v2/) of the K/V Engine. See examples below for how to [use v1](#using-kv-version-1) as well as [other non-K/V engines](#other-secret-engines).
|
|
||||||
|
|
||||||
<!-- TOC -->
|
<!-- TOC -->
|
||||||
|
|
||||||
- [Example Usage](#example-usage)
|
- [Example Usage](#example-usage)
|
||||||
|
|
@ -25,8 +17,6 @@ By default, this action pulls from [Version 2](https://www.vaultproject.io/docs
|
||||||
- [Set Output Variable Name](#set-output-variable-name)
|
- [Set Output Variable Name](#set-output-variable-name)
|
||||||
- [Multiple Secrets](#multiple-secrets)
|
- [Multiple Secrets](#multiple-secrets)
|
||||||
- [Nested Secrets](#nested-secrets)
|
- [Nested Secrets](#nested-secrets)
|
||||||
- [Using K/V version 1](#using-kv-version-1)
|
|
||||||
- [Custom K/V Engine Path](#custom-kv-engine-path)
|
|
||||||
- [Other Secret Engines](#other-secret-engines)
|
- [Other Secret Engines](#other-secret-engines)
|
||||||
- [Adding Extra Headers](#adding-extra-headers)
|
- [Adding Extra Headers](#adding-extra-headers)
|
||||||
- [Vault Enterprise Features](#vault-enterprise-features)
|
- [Vault Enterprise Features](#vault-enterprise-features)
|
||||||
|
|
@ -51,9 +41,9 @@ jobs:
|
||||||
url: https://vault.mycompany.com:8200
|
url: https://vault.mycompany.com:8200
|
||||||
token: ${{ secrets.VaultToken }}
|
token: ${{ secrets.VaultToken }}
|
||||||
secrets: |
|
secrets: |
|
||||||
ci/aws accessKey | AWS_ACCESS_KEY_ID ;
|
secret/data/ci/aws accessKey | AWS_ACCESS_KEY_ID ;
|
||||||
ci/aws secretKey | AWS_SECRET_ACCESS_KEY ;
|
secret/data/ci/aws secretKey | AWS_SECRET_ACCESS_KEY ;
|
||||||
ci npm_token
|
secret/data/ci npm_token
|
||||||
# ...
|
# ...
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
@ -100,11 +90,11 @@ Each secret request consists of the `path` and the `key` of the desired secret,
|
||||||
|
|
||||||
### Simple Key
|
### Simple Key
|
||||||
|
|
||||||
To retrieve a key `npmToken` from path `ci` that has value `somelongtoken` from vault you could do:
|
To retrieve a key `npmToken` from path `secret/data/ci` that has value `somelongtoken` from vault you could do:
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
with:
|
with:
|
||||||
secrets: ci npmToken
|
secrets: secret/data/ci npmToken
|
||||||
```
|
```
|
||||||
|
|
||||||
`vault-action` will automatically normalize the given secret selector key, and set the follow as environment variables for the following steps in the current job:
|
`vault-action` will automatically normalize the given secret selector key, and set the follow as environment variables for the following steps in the current job:
|
||||||
|
|
@ -134,7 +124,7 @@ However, if you want to set it to a specific name, say `NPM_TOKEN`, you could do
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
with:
|
with:
|
||||||
secrets: ci npmToken | NPM_TOKEN
|
secrets: secret/data/ci npmToken | NPM_TOKEN
|
||||||
```
|
```
|
||||||
|
|
||||||
With that, `vault-action` will now use your requested name and output:
|
With that, `vault-action` will now use your requested name and output:
|
||||||
|
|
@ -161,65 +151,18 @@ This action can take multi-line input, so say you had your AWS keys stored in a
|
||||||
```yaml
|
```yaml
|
||||||
with:
|
with:
|
||||||
secrets: |
|
secrets: |
|
||||||
ci/aws accessKey | AWS_ACCESS_KEY_ID ;
|
secret/data/ci/aws accessKey | AWS_ACCESS_KEY_ID ;
|
||||||
ci/aws secretKey | AWS_SECRET_ACCESS_KEY
|
secret/data/ci/aws secretKey | AWS_SECRET_ACCESS_KEY
|
||||||
```
|
```
|
||||||
|
|
||||||
### Nested Secrets
|
|
||||||
|
|
||||||
By default, `vault-action` will read the key from `data.data` in the response for the K/V v2 engine (default), or `data` for K/V v1 and other Secret Engines (see below for more info).
|
|
||||||
If you need to retrieve a sub-key from a JSON document, or are interested in some other component of the Vault response, you can specify a different key as the path to the desired out.
|
|
||||||
|
|
||||||
_**Important**_: You must specify an [Output Variable Name](#set-output-variable-name) when using this method.
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
with:
|
|
||||||
secrets: |
|
|
||||||
my/path pair.key | NESTED_SECRET ;
|
|
||||||
```
|
|
||||||
|
|
||||||
Under the covers, we're using [JSONata](https://jsonata.org/) to provide the querying functionality. Any valid JSONata syntax is valid here, and will be outputted as a `JSON.stringify`-ied result.
|
|
||||||
|
|
||||||
### Using K/V version 1
|
|
||||||
|
|
||||||
By default, `vault-action` expects a K/V engine using [version 2](https://www.vaultproject.io/docs/secrets/kv/kv-v2.html).
|
|
||||||
|
|
||||||
In order to work with a [v1 engine](https://www.vaultproject.io/docs/secrets/kv/kv-v1/), the `kv-version` parameter may be passed:
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
with:
|
|
||||||
kv-version: 1
|
|
||||||
```
|
|
||||||
|
|
||||||
## Custom K/V Engine Path
|
|
||||||
|
|
||||||
When you enable the K/V Engine, by default it's placed at the path `secret`, so a secret named `ci` will be accessed from `secret/ci`. However, [if you enabled the secrets engine using a custom `path`](https://www.vaultproject.io/docs/commands/secrets/enable/#inlinecode--path-4), you
|
|
||||||
can pass it as follows:
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
with:
|
|
||||||
path: my-secrets
|
|
||||||
secrets: ci npmToken
|
|
||||||
```
|
|
||||||
|
|
||||||
This way, the `ci` secret in the example above will be retrieved from `my-secrets/ci`.
|
|
||||||
|
|
||||||
## Other Secret Engines
|
## Other Secret Engines
|
||||||
|
|
||||||
While this action primarily supports the K/V engine, it is possible to request secrets from other engines in Vault.
|
Vault Action currently supports retrieving secrets from any engine where secrets
|
||||||
|
are retrieved via `GET` requests. This means secret engines such as PKI are currently
|
||||||
|
not supported due to their requirement of sending parameters along with the request
|
||||||
|
(such as `common_name`).
|
||||||
|
|
||||||
To do so when specifying the `Secret Path`, just append a leading forward slash (`/`) and specify the path as described in the Vault API documentation.
|
For example, to request a secret from the `cubbyhole` secret engine:
|
||||||
|
|
||||||
For example, to retrieve a stored secret from the [`cubbyhole` engine](https://www.vaultproject.io/api-docs/secret/cubbyhole/), assuming you have a stored secret at the path `foo` with the contents:
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"foo": "bar",
|
|
||||||
"zip": "zap"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
You could request the contents like so:
|
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
with:
|
with:
|
||||||
|
|
@ -247,21 +190,6 @@ steps:
|
||||||
run: "my-cli --token '${{ steps.secrets.outputs.MY_KEY }}'"
|
run: "my-cli --token '${{ steps.secrets.outputs.MY_KEY }}'"
|
||||||
```
|
```
|
||||||
|
|
||||||
Secrets pulled from the same `Secret Path` are cached by default. So if you, for example, are using the `aws` engine and retrieve a key, only a single key for a given path is returned.
|
|
||||||
|
|
||||||
e.g.:
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
with:
|
|
||||||
secrets: |
|
|
||||||
/aws/creds/ci access_key | AWS_ACCESS_KEY_ID ;
|
|
||||||
/aws/creds/ci secret_key | AWS_SECRET_ACCESS_KEY
|
|
||||||
```
|
|
||||||
|
|
||||||
would work fine.
|
|
||||||
|
|
||||||
*NOTE: Per [Nested Secrets](#nested-secrets), the `Key` is pulled from the `data` property of the response.*
|
|
||||||
|
|
||||||
## Adding Extra Headers
|
## Adding Extra Headers
|
||||||
|
|
||||||
If you ever need to add extra headers to the vault request, say if you need to authenticate with a firewall, all you need to do is set `extraHeaders`:
|
If you ever need to add extra headers to the vault request, say if you need to authenticate with a firewall, all you need to do is set `extraHeaders`:
|
||||||
|
|
@ -269,8 +197,8 @@ If you ever need to add extra headers to the vault request, say if you need to a
|
||||||
```yaml
|
```yaml
|
||||||
with:
|
with:
|
||||||
secrets: |
|
secrets: |
|
||||||
ci/aws accessKey | AWS_ACCESS_KEY_ID ;
|
secret/ci/aws accessKey | AWS_ACCESS_KEY_ID ;
|
||||||
ci/aws secretKey | AWS_SECRET_ACCESS_KEY
|
secret/ci/aws secretKey | AWS_SECRET_ACCESS_KEY
|
||||||
extraHeaders: |
|
extraHeaders: |
|
||||||
X-Secure-Id: ${{ secrets.SECURE_ID }}
|
X-Secure-Id: ${{ secrets.SECURE_ID }}
|
||||||
X-Secure-Secret: ${{ secrets.SECURE_SECRET }}
|
X-Secure-Secret: ${{ secrets.SECURE_SECRET }}
|
||||||
|
|
@ -295,9 +223,9 @@ steps:
|
||||||
token: ${{ secrets.VaultToken }}
|
token: ${{ secrets.VaultToken }}
|
||||||
namespace: ns1
|
namespace: ns1
|
||||||
secrets: |
|
secrets: |
|
||||||
ci/aws accessKey | AWS_ACCESS_KEY_ID ;
|
secret/ci/aws accessKey | AWS_ACCESS_KEY_ID ;
|
||||||
ci/aws secretKey | AWS_SECRET_ACCESS_KEY ;
|
secret/ci/aws secretKey | AWS_SECRET_ACCESS_KEY ;
|
||||||
ci npm_token
|
secret/ci npm_token
|
||||||
```
|
```
|
||||||
|
|
||||||
## Reference
|
## Reference
|
||||||
|
|
@ -309,8 +237,6 @@ Here are all the inputs available through `with`:
|
||||||
| `url` | The URL for the vault endpoint | | ✔ |
|
| `url` | The URL for the vault endpoint | | ✔ |
|
||||||
| `secrets` | A semicolon-separated list of secrets to retrieve. These will automatically be converted to environmental variable keys. See README for more details | | ✔ |
|
| `secrets` | A semicolon-separated list of secrets to retrieve. These will automatically be converted to environmental variable keys. See README for more details | | ✔ |
|
||||||
| `namespace` | The Vault namespace from which to query secrets. Vault Enterprise only, unset by default | | |
|
| `namespace` | The Vault namespace from which to query secrets. Vault Enterprise only, unset by default | | |
|
||||||
| `path` | The path of a non-default K/V engine | | |
|
|
||||||
| `kv-version` | The version of the K/V engine to use. | `2` | |
|
|
||||||
| `method` | The method to use to authenticate with Vault. | `token` | |
|
| `method` | The method to use to authenticate with Vault. | `token` | |
|
||||||
| `token` | The Vault Token to be used to authenticate with Vault | | |
|
| `token` | The Vault Token to be used to authenticate with Vault | | |
|
||||||
| `roleId` | The Role Id for App Role authentication | | |
|
| `roleId` | The Role Id for App Role authentication | | |
|
||||||
|
|
|
||||||
|
|
@ -7,7 +7,7 @@ const { when } = require('jest-when');
|
||||||
|
|
||||||
const { exportSecrets } = require('../../src/action');
|
const { exportSecrets } = require('../../src/action');
|
||||||
|
|
||||||
const vaultUrl = `http://${process.env.VAULT_HOST || '0.0.0.0'}:${process.env.VAULT_PORT || '8200'}`;
|
const vaultUrl = `http://${process.env.VAULT_HOST || 'localhost'}:${process.env.VAULT_PORT || '8200'}`;
|
||||||
|
|
||||||
describe('integration', () => {
|
describe('integration', () => {
|
||||||
beforeAll(async () => {
|
beforeAll(async () => {
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue