Commit e7f0ca15 authored by Pierre Smeyers's avatar Pierre Smeyers
Browse files

doc: improve debug instructions

parent f50f05a7
Loading
Loading
Loading
Loading
+30 −16
Original line number Diff line number Diff line
@@ -78,11 +78,11 @@ The tool requires the following environment variables to be set (as GitLab CI se
| `VAULT_BASE_AUTH_APPROLE_PATH`| The base [AppRole authentication](https://www.vaultproject.io/api-docs/auth/approle) API path | `/auth/approle` |
| `VAULT_BASE_AUTH_JWT_PATH`    | The base [JWT/OIDC authentication](https://www.vaultproject.io/api-docs/auth/jwt) API path | `/auth/jwt` |
| `VAULT_BASE_KV_SECRETS_PATH`  | The base [Key/Value secrets](https://www.vaultproject.io/api-docs/secret/kv/kv-v1) API path | `/secret` |
| `VAULT_ROLE_ID`   | The [AppRole](https://www.vaultproject.io/docs/auth/approle) RoleID | _none_ (required to use the [AppRole](https://www.vaultproject.io/docs/auth/approle) Auth Method) |
| `VAULT_SECRET_ID` | The [AppRole](https://www.vaultproject.io/docs/auth/approle) SecretID | _none_  (required to use the [AppRole](https://www.vaultproject.io/docs/auth/approle) Auth Method) |
| `VAULT_TOKEN`     | The token to use | _none_  (required to use the [Token](https://www.vaultproject.io/docs/auth/token) Auth Method) |
| `VAULT_JWT_TOKEN` | The signed [JSON Web Token](https://en.wikipedia.org/wiki/JSON_Web_Token) to login | `$CI_JOB_JWT` |
| `VAULT_JWT_ROLE`  | Name of the role against which the login is being attempted | `default_role`  (used with the [JWT/OIDC](https://www.vaultproject.io/docs/auth/jwt) Auth Method) |
| `VAULT_ROLE_ID`   | The [AppRole](https://www.vaultproject.io/docs/auth/approle) RoleID <br/>_Required for the [AppRole](https://www.vaultproject.io/docs/auth/approle) Auth Method_ | _none_ |
| `VAULT_SECRET_ID` | The [AppRole](https://www.vaultproject.io/docs/auth/approle) SecretID <br/>_Required for the [AppRole](https://www.vaultproject.io/docs/auth/approle) Auth Method_ | _none_ |
| `VAULT_TOKEN`     | The authentication token <br/>_Required for the [Token](https://www.vaultproject.io/docs/auth/token) Auth Method_ | _none_ |
| `VAULT_JWT_TOKEN` | The signed [JSON Web Token](https://en.wikipedia.org/wiki/JSON_Web_Token) to login <br/>_Required for the [JWT/OIDC](https://www.vaultproject.io/docs/auth/jwt) Auth Method_ | `$CI_JOB_JWT` |
| `VAULT_JWT_ROLE`  | Name of the role against which the login is being attempted  <br/>_Required for the [JWT/OIDC](https://www.vaultproject.io/docs/auth/jwt) Auth Method_ | `default_role` |

If no authentication parameter is set, the image will emit an error log at startup.

@@ -123,24 +123,38 @@ Depending on what is available in your docker image, you may request the service

You might want to test/debug whether you have the right secret ID, role ID, secret path, secret key or so.

Simply run the Docker image with:
You may either use a remote Vault server, or run one locally using the 
[Vault Docker image](https://hub.docker.com/_/vault) in dev mode on port 8200, specifying the root token value:

```bash
docker run -i --rm -it -p 80:80 \
    --env VAULT_BASE_URL=$VAULT_BASE_URL \
    --env VAULT_SECRET_ID=$VAULT_SECRET_ID \
    --env VAULT_ROLE_ID=$VAULT_ROLE_ID \
    registry.gitlab.com/to-be-continuous/tools/vault-secrets-provider:master
docker run -d -p 8200:8200 --env VAULT_DEV_ROOT_TOKEN_ID=dev-token vault 
```

:warning: replace `$VAULT_BASE_URL`, `$VAULT_SECRET_ID` and `$VAULT_ROLE_ID` with yours.
If you need to override other variables, simply use the `--env` CLI option.
Then run the Vault Secrets Provider Docker image:

Then you may request the API using `curl` or `wget` as follows:
```bash
# adapt the Vault server URL to the one you chose
# use this value if using a local Vault server
export VAULT_BASE_URL=http://host.docker.internal:8200/v1
# maybe use other authentication variables (depending on your Auth Method)
export VAULT_TOKEN=dev-token
docker run -it -p 80:80 --env VAULT_BASE_URL --env VAULT_TOKEN registry.gitlab.com/to-be-continuous/tools/vault-secrets-provider:master
```

Then you may simply debug the API using `curl` with the `-w "\n>> status: %{http_code}\n"` option. Examples:

```bash
curl -sSf "http://localhost/api/secrets/b7ecb6ebabc231/my-backend/prod?field=token"
wget -O - "http://localhost/api/secrets/b7ecb6ebabc231/my-backend/prod?field=token"
$ curl -s -w "\n>> status: %{http_code}\n" "http://localhost/api/secrets/b7ecb6ebabc231/my-backend/prod?field=token"
ŧ0k3N
>> status: 200

$ curl -s -w "\n>> status: %{http_code}\n" "http://localhost/api/secrets/no/such/path?field=token"
Vault server error on GET http://host.docker.internal:8200/v1/secret/data/no/such/path > 
>> status: 404

$ curl -s -w "\n>> status: %{http_code}\n" "http://localhost/api/secrets/b7ecb6ebabc231/my-backend/prod?field=no.such.field"
Invalid key path 'data.no.such.field' > No such object: 'data.no.such.field'
>> status 400
```

_et voilà_ :)