Skip to content

BESTSELLER/harpocrates

Repository files navigation

Harpocrates

Harpocrates was the god of silence, secrets and confidentiality


CircleCI GitHub repo size GitHub All Releases GitHub


Harpocrates is a small application that can be used to pull secrets from HashiCorp Vault. It can output the secrets in different formats:

  • JSON, which is simple key-values.
    {
      "KEY": "value",
      "FOO": "bar"
    }
  • source ready env file e.g.
    export KEY=value
    export FOO=bar
  • Raw key values.
    KEY=value
    FOO=bar
  • Raw value in a separate file.
    value



Harpocrates is designed such it can be used as an init- or sidecar container in Kubernetes. In this scenario it uses the ServiceAccount token in /var/run/secrets/kubernetes.io/serviceaccount/token and exchanges this for a Vault token by posting it to /auth/kubernetes/login.

This requires that the Kubernetes Auth Method is enabled in Vault.



Authentication

The easiest way to authenticate is to use your Vault token:

harpocrates --vault-token "sometoken"

This can also be specified as the environment var VAULT_TOKEN

GCP Workload identity

When running in GCP you can use the GCP Workload identity to authenticate to Vault. This requires that the GCP Auth Method is enabled in Vault and your service account has been given access to secrets. Check this blog post for more info : Serverless Secrets with Google Cloud Run and Hashicorp Vault

To use, set the gcpWorkloadID flag to true.



Usage

In harpocrates you can specify which secrets to pull in 3 different ways.

YAML file

yaml is a great options for readability and replication of configs. yaml options are:

Option Required Value default
format no one of: env, json, secret, yaml env
output yes /path/to/output/folder -
owner no UID of the user e.g 0, can be set on "root" and secret level current user
prefix no prefix, can be set on any level -
uppercase no will uppercase prefix and key false
append no appends secrets to a file true
secrets yes an array of secret paths -
gcpWorkloadID no GCP workload identity, useful when running in GCP false

Example yaml file at examples/secret.yaml


run harpocrates with the -f flag to fetch secrets from your yaml spec.

harpocrates -f /path/to/file.yaml

Inline spec

You can specify the exact same options in inline json/yaml as in the yaml spec. Mostly for programmatic use, as readability is way worse than the yaml spec.

harpocrates '{"format":"env","output":"/secrets","prefix":"PREFIX_","secrets":["secret/data/secret/dev",{"secret/data/foo":{"keys":["APIKEY"]}}]}'

Or if you prefer you can do it like this:

harpocrates '{
  "format": "env",
  "output": "/secrets",
  "prefix": "PREFIX_",
  "secrets": [
    "secret/data/secret/dev",
    {
      "secret/data/foo": {
        "keys": [
          "APIKEY"
        ]
      }
    }
  ]
}'

Or as yaml

harpocrates 'format: env
output: "/secrets"
prefix: PREFIX_
secrets:
  - secret/data/secret/dev
  - secret/data/foo:
      prefix: TEST_
      keys:
       - APIKEY
       - BAR:
           prefix: "BOTTOM_"
       - TOPSECRET:
           saveAsFile: true
  - secret/data/bar:
      format: json
      filename: something.json
      owner: 29'

CLI Parameters

The third option is to specify the options as parameters in the cli.

harpocrates --format "env" --secret "/secret/data/somesecret" --prefix "PREFIX_" --output "/secrets"

There is not the same granularity as in the json and yaml specs. e.g. prefix can only exist on the top level.



CLI and ENV Options

Flag Env Var Values Default
vault-address VAULT_ADDR https://vaulturl -
auth-name AUTH_NAME Vault auth name, used at login -
role-name ROLE_NAME Vault role name, used at login -
token-path TOKEN_PATH /path/to/token, uses clustername and path to login and exchange a vault token which is used in vault_token /var/run/secrets/kubernetes.io/serviceaccount/token
vault-token VAULT_TOKEN token as a string. If empty token_path will be queried -
format - env, json, secret or yaml env
output - /path/to/output /tmp/secrets.env
owner - UID of the user e.g 0 current user
prefix - prefix keys, eg. K8S_ -
uppercase - will uppercase prefix and key false
secret - vault path /secretengine/data/some/secret -
append - Appends secrets to a file true
- HARPOCRATES_FILENAME overwrites the default output filename -
gcpWorkloadID GCP_WORKLOAD_ID set to true to enable GCP workload identity, useful when running in GCP false
- CONTINUOUS set to true to run harpocrates in a loop and fetch secrets every 1 minute, useful as a sidecar false
- INTERVAL set the interval in minutes for the continuous mode 1


Kubernetes

When running harpocrates or cloudrun as an init container or sidecar you have to mount a volume to pass on the exported secrets to your main application. Then you can either chose to source the env file or simply just read the json formatted file. Harpocrates will startup and export the secrets in a matter of seconds.

An example can be found at examples/deployment.yaml

Sidecar

To run harpocrates as a sidecar you have to set the CONTINUOUS env var to true. Harpocrates will then run in a loop and fetch secrets every 1 minute. The shortest secret refresh interval is 1 minute and can be increased using the INTERVAL variable.



CircleCI Orb

Docs in the orb folder



Contribution

Issues and pull requests are more than welcome.