{"id":20196650,"url":"https://github.com/dbschenker/vaultpal","last_synced_at":"2026-01-02T10:18:10.097Z","repository":{"id":185419740,"uuid":"642843342","full_name":"dbschenker/vaultpal","owner":"dbschenker","description":" Your friendly pal for using HashiCorp Vault ","archived":false,"fork":false,"pushed_at":"2025-04-02T06:28:21.000Z","size":397,"stargazers_count":12,"open_issues_count":0,"forks_count":2,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-04-02T07:24:16.247Z","etag":null,"topics":["go","security-tools","vault"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dbschenker.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-05-19T13:22:24.000Z","updated_at":"2025-04-02T06:15:08.000Z","dependencies_parsed_at":null,"dependency_job_id":"36265f6f-e1d1-486e-a6ac-c8ae1062bc8a","html_url":"https://github.com/dbschenker/vaultpal","commit_stats":null,"previous_names":["dbschenker/vaultpal"],"tags_count":17,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dbschenker%2Fvaultpal","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dbschenker%2Fvaultpal/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dbschenker%2Fvaultpal/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dbschenker%2Fvaultpal/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dbschenker","download_url":"https://codeload.github.com/dbschenker/vaultpal/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248200137,"owners_count":21063833,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["go","security-tools","vault"],"created_at":"2024-11-14T04:25:12.738Z","updated_at":"2026-01-02T10:18:10.092Z","avatar_url":"https://github.com/dbschenker.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# vaultpal :vulcan_salute:\n\u003e { your pal for using vault }\n\nAt DB Schenker, we use [HashiCorp Vault](https://www.vaultproject.io/) extensively to automate access to secrets\n(e.g. application credentials), and systems such as *Kubernetes* or *AWS*. \n\nEven though the official Vault CLI and the [HTTP API](https://developer.hashicorp.com/vault/api-docs) provide the necessary \nmeans to access all Vault features programmatically, their usage can become overly complex for end-users who simply want \nto manage the accesses they need for their daily work.\n\nThis is where vaultpal comes into play: It wraps common access management functions into higher level (sub)commands\nthat don't require deep Vault know-how or excessive configuration. As an example, vaultpal can empower users to obtain \ntemporary, limited-privilege credentials from the AWS Security Token Service (STS) through HashiCorp Vault with a single \ncommand call.\n\n## Releases\n\nCheck the [releases](https://github.com/dbschenker/vaultpal/releases) section for the most recent binaries that are suitable for your operating system.\n\nPlease note that vaultpal has been thoroughly tested on macOS (`*darwin` binaries) and Linux, but not on Windows. \nThe binary should execute without issues, but there may be subtle differences, e.g. in the handling of file locations.\nAlternatively, consider [Windows Subsystem for Linux](https://docs.microsoft.com/de-de/windows/wsl/install-win10).\n\n\n## Setup\n\n1. Extract the go binary, place it on your `$PATH` and make it executable.\n    ```bash\n      echo $PATH\n      chmod a+x /path/to/vaultpal_binary\n      cp /path/to/vaultpal_binary /element/of/your/$PATH\n    ``` \n   Please note that $PATH output will look like this:\n    ```bash\n      /Users/your_user/.local/bin:/Users/your_user/.pyenv/plugins/pyenv-virtualenv/shims:\n    ```\n    That is, each element is separated from others by \u003cb\u003e:\u003c/b\u003e . So in this example: \n    ```/element/of/your/$PATH``` could be: ```/Users/your_user/.local/bin ``` . You may need to use this command with sudo.\n\n2. Check the installation with:\n   ```bash\n    vaultpal version\n    ```\n3. (optional) install completion (bash/zsh). \n    ```bash\n    echo 'source \u003c(vaultpal completion bash)' \u003e\u003e~/.bashrc\n    ```\n4. (optional) define an alias\n    ```bash\n    echo 'alias vp=vaultpal' \u003e\u003e~/.bashrc\n    echo 'complete -F __start_vaultpal vp' \u003e\u003e~/.bashrc\n    ```\n   \n## Docker Container Images\n\nReleased vaultpal versions are build for multiple architectures and pushed to the public GitHub Container Registry (https://ghcr.io).\n\n```\n$ docker pull ghcr.io/dbschenker/vaultpal:1.6.0\n$ docker run --rm dbschenker/vaultpal:1.6.0 version\nv1.6.0 (commit: 319f6c3)\n```\n\n## Usage\n\n- perform login with vault cli since vaultpal relies on a valid existing token, e.g.:\n    ```bash\n    vault login -method=oidc\n    ```\n\n- just launch without arguments to get an overview of available commands and flags\n   ```\n    vaultpal\n          { vault~Pal 👍 }\n         °- (🕶 ) v1.5.2 -°\n\n   vault~Pal 👍 will help you using vault in your daily work.\n   \n   Usage:\n     vaultpal [flags]\n     vaultpal [command]\n   \n   Available Commands:\n     completion  Generate shell completion scripts\n     export      Export various types of resources to shell\n     help        Help about any command\n     switch      Switch between roles\n     timer       Display the remaining TTL of your vault token\n     version     Print version of vaultpal\n     write       Write various types of resources\n   \n   Flags:\n         --config string      config file (default is $HOME/.vaultpal.yaml)\n     -h, --help               help for vaultpal\n     -v, --verbosity string   Log level (debug, info, warn, error, fatal, panic (default \"info\")\n   \n   Use \"vaultpal [command] --help\" for more information about a command.\n   ```\n\n## Features  \n\n### Kubeconfig\n\n1. Call vaultpal to create a kubeconfig file\n    ```bash\n    vaultpal write kubeconfig sandbox master\n    ```\n    \n2. vaultpal will write kubeconfig file in home directory:\n    ```bash\n    ~/.vaultpal/kube/config\n    ``` \n3. Enable usage of kubeconfig file with:\n   ```bash\n   export KUBECONFIG=~/.vaultpal/kube/config\n   ```\n4. Note that vaultpal will store a kubeconfig for each cluster with the cluster name as context name. This enables the usage of different clusters at the same time\n\n\n### Switch Role\n\n1. Call vaultpal to switch to a token role\n    ```bash\n    vaultpal switch role k8s-admin\n    ```\n2. vaultpal will create a new token for given role and write it to vault token file\n3. Use vault cli with the role token\n\n### Export AWS STS Credentials\n\n1. Use vaultpal to create AWS STS credentials with vault\n    ```bash\n    vaultpal export awssts mytopic-prod-admin\n    ```\n2. vaultpal will use vault aws secret engine to create AWS STS credentials. The default secret engine path is \"aws\"\n3. The credentials will be printed as bash export commands.\n\n### Use Alias function\n\nvaultpal provides a bash alias function to wrap the vaultpal command with direct export of the credentials to the current shell.\n\n1. Get the alias function\n    ```bash\n    vaultpal export awssts -a\n    ```\n2. Or use it directly in alias definition, e.g.:\n    ```bash\n    alias vpalsts=\"$(vaultpal export awssts -a)\"\n    ```\n   Then you will get the credentials exported to current shell and can use it directly, e.g.:\n    ```bash\n    vpalsts mytopic-prod-admin\n    ```\n### Export AWS web console URL to shell\n\n1. Use vaultpal to create temporary sign-in URLs to access the AWS Web Console with a single click. If the environment variable AWS_REGION is set, the URL will redirect to the region specific console URL.\n   ```\n   vaultpal -v warn export awsconsole myapp-prod-admin\n   https://signin.aws.amazon.com/federation?Action=login\u0026Issuer=https://(...)\n   ```\n\n## Configuration\n\nThe following section describes central configurations, that are required\nfor vaultpal kubeconfig functions\n\n### Kubeconfig\n\nIn order to render kubeconfig files, vaultpal requires meta information about the \nkubernetes cluster. Therefore, a cluster configuration object must be stored in vault providing\nthe required information. The configuration object must be stored in a kv secret engine version 2 at mount path \"kv\".\nThe configuration must be accessible for all vaultpal users\n\nExample:\nConfiguration for a kubernetes cluster called \"bibi\" must be stored at vault path\n`kv/vaultpal/k8s/clusters/bibi`\nwith data:\n```json\n{\n  \"name\":   \"bibi\",\n  \"pki\":    \"k8s-bibi-pki-kube\",\n  \"server\": \"https://api.bibi.mytopic.com\"\n}\n```\n### Cluster Alias\n\nvaultpal supports the definition of an alias to a kubernetes cluster. This is useful if you want to use a generic\nendpoint like \"int\" or \"prod\" pointing to a cluster.\n\nExample:\nConfiguration for an alias named \"int\" pointing to a kubernetes cluster called \"bibi\" must be stored at vault path\n`kv/vaultpal/k8s/clusters/int`\nwith data:\n```json\n{\n  \"name\":   \"int\",\n  \"alias\":  \"bibi\",\n  \"server\": \"https://api.int.mytopic.com\"\n}\n```\nBased on the alias value \"bibi\", vaultpal will read the configuration for cluster \"bibi\" in order to render the required certs and keys (pki).  \n\n### Environment Variables\n\n| Variable                 | Usage                                                          |\n|--------------------------|----------------------------------------------------------------|\n| VAULTPAL_NP_URL          | URL of Vault non-production environment, used for prompt label |\n| VAULTPAL_PR_URL          | URL of Vault production environment, used for prompt label     |\n| VAULTPAL_KUBECONFIG_FILE | Custom location of kubeconfig file                             |\n\n## Contributing\n\nPull requests are welcome. For major changes, please open an issue first to discuss your idea.\n\n## License\n\n[MIT](https://choosealicense.com/licenses/mit/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdbschenker%2Fvaultpal","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdbschenker%2Fvaultpal","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdbschenker%2Fvaultpal/lists"}