{"id":13463728,"url":"https://github.com/Boostport/kubernetes-vault","last_synced_at":"2025-03-25T09:31:00.731Z","repository":{"id":109787364,"uuid":"74663841","full_name":"Boostport/kubernetes-vault","owner":"Boostport","description":"Use Vault to store secrets for Kubernetes!","archived":true,"fork":false,"pushed_at":"2021-03-15T22:59:29.000Z","size":376,"stargazers_count":939,"open_issues_count":0,"forks_count":134,"subscribers_count":34,"default_branch":"main","last_synced_at":"2024-10-29T16:19:46.113Z","etag":null,"topics":["kubernetes","vault"],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Boostport.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"License","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2016-11-24T10:44:13.000Z","updated_at":"2024-10-18T18:16:38.000Z","dependencies_parsed_at":"2024-01-13T17:55:51.617Z","dependency_job_id":"fd7fd1e1-8993-4f26-a2e2-f291f3f1b060","html_url":"https://github.com/Boostport/kubernetes-vault","commit_stats":null,"previous_names":[],"tags_count":19,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Boostport%2Fkubernetes-vault","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Boostport%2Fkubernetes-vault/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Boostport%2Fkubernetes-vault/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Boostport%2Fkubernetes-vault/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Boostport","download_url":"https://codeload.github.com/Boostport/kubernetes-vault/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245435074,"owners_count":20614823,"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":["kubernetes","vault"],"created_at":"2024-07-31T14:00:27.470Z","updated_at":"2025-03-25T09:31:00.213Z","avatar_url":"https://github.com/Boostport.png","language":"Go","funding_links":[],"categories":["Tools","Secret generation and management","Go"],"sub_categories":["[Jenkins](#jenkins)"],"readme":"# No Longer Being Maintained.\n\nThe integration between Vault and Kubernetes has been greatly improved over the last few years and Kubernetes-Vault is\nno longer required for deployments using recent versions of Vault and Kubernetes.\n\nTo use Vault with Kubernetes directly, you can use\nthe [Kubernetes Auth Method](https://www.vaultproject.io/docs/auth/kubernetes)\nand the [Vault Agent](https://www.vaultproject.io/docs/agent) as a side-car to retrieve and renew secrets from Vault.\n\n# Kubernetes Vault Integration\n\nThe Kubernetes-Vault project allows pods to automatically receive a Vault token using\nVault's [AppRole auth backend](https://www.vaultproject.io/docs/auth/approle.html).\n\n![flow diagram](flow-diagram.png)\n\n## Highlights\n\n* Secure by default. The Kubernetes-Vault controller does not allow using root tokens to authenticate against Vault.\n* Prometheus metrics endpoint over http or https, with optional TLS client authentication.\n* Supports using Vault as a CA or an external CA for all components with TLS support.\n* High availability mode using Raft, so that if the leader goes down, a follower can take over immediately.\n* Peer discovery using Kubernetes services and endpoints and gossip to propagate peer changes across the cluster.\n\n## Prerequisites:\n* Vault should be 0.6.3 and above.\n* You must use Kubernetes 1.6.0 and above as we rely on init containers (in beta) to accept the token.\n* For Kubernetes 1.5.x and below, please use an older versions of Kubernetes-Vault by referencing the [compatibility table](#kubernetes-version-compatibility).\n* You must generate a periodic token with the correct policy to generate `secret_id`s using the AppRole backend.\n* The Kubernetes-Vault controller uses the Kubernetes service account to watch for new pods. This service account must have the appropriate permissions.\n* Your app should use a [Vault client](https://www.vaultproject.io/api/libraries.html) to renew the token and any secrets you request from Vault.\n* You should configure Vault to use HTTPS, so that the authentication token and any other secrets cannot be sniffed.\n* If using RBAC, the Kubernetes-Vault controller needs the following permissions\n  * `get` it's endpoint (headless service)\n  * `list` and `watch` `pods` in all namespaces.\n\n## Get started\nTo run Kubernetes-Vault on your cluster, follow the [quick start guide](deployments/quick-start/README.md).\n\n## Best practices\nSee our list of [best practices](best-practices.md).\n\n## Token format\nThe token information is encoded as JSON and written to a file called `vault-token`. Here's an example of what it looks like:\n\n```json\n{\n  \"clientToken\":\"91526d9b-4850-3405-02a8-aa29e74e17a5\",\n  \"accessor\":\"476ea048-ded5-4d07-eeea-938c6b4e43ec\",\n  \"leaseDuration\":3600,\n  \"renewable\":true,\n  \"vaultAddr\":\"https://vault:8200\"\n}\n```\n\nYour application should parse the JSON representation and renew the `clientToken` using the `leaseDuration` as a guide.\n\nIf you ask the init container to not login using the `role_id` and `secret_id` to retrieve the token by setting the\n`RETRIEVE_TOKEN` environment variable of the init container to `false`, the `secret_id` and any related information is\nencoded as JSON written to a file called `vault-secret-id` instead. Here's an example of what it looks like:\n\n```json\n{\n  \"roleId\":\"313b0821-4ff6-1df8-54dd-c3eea5d3b8b1\",\n  \"secretId\":\"3c3ebf1f-8fa5-8cce-e3e8-f769e386bd4b\",\n  \"accessor\":\"5c8b7cb5-5d8e-0dbf-be27-12604f5b64aa\",\n  \"vaultAddr\":\"https://vault:8200\"\n}\n```\n\nIf you choose to use Kubernetes-vault in this mode, it will be your application's responsibility to use the `secret_id`\nand `role_id` pair to login to the Vault server and retrieve an auth token.\n\nAlternatively, you can choose to not have the init container unwrap the secret, and leave that responsibility up to your app. To do this, set `UNWRAP_SECRET` to `false`, and the wrapped `secret_id` and any related information will be encoded as JSON and written to a file called `vault-wrapped-secret-id`. Here's an example of what it looks like:\n\n```json\n{\n  \"roleId\":\"313b0821-4ff6-1df8-54dd-c3eea5d3b8b1\",\n  \"wrappedSecretId\":\"2179ad51-cfb5-03de-dad7-2c25746b38e3\",\n  \"vaultAddr\":\"https://vault:8200\",\n  \"ttl\":60\n}\n```\n\n## CA bundle\nIf you are connecting to Vault over https (highly recommended for production), you will find the CA bundle for Vault in\nthe file `ca.crt`. Use the CA bundle when connecting to Vault using your application, so that the identity of Vault is\nverified.\n\n## Configuration\nThe project consists of 2 containers, a controller container that watches the Kubernetes cluster and pushes `secret_id`s\nto pods and an init container that receives the `secret_id` and exchanges it for an auth token. The controller is\nconfigured using a YAML file and the init container uses environment variables. The init container also requires\nconfiguration using Kubernetes annotations.\n\nFor full examples of configuration files, check out the ConfigMaps in the [quick start](deployments/quick-start/kubernetes-vault.yaml) and [secured](deployments/secured-external-ca/kubernetes-vault.yaml) examples.\n\n### Kubernetes-Vault controller configuration\nThe Kubernetes-Vault is configured using a YAML file. We recommend using a ConfigMap to mount the file and any other files\n( such as certificates and private keys, if using an external CA) into the controller's pod.\n\nThe controller automatically expands any environment variables used in the configuration specified using the `$VARIABLE` or \n`${VARIABLE}` notation. For example, if you set `raftDir: ${MY_DIR}` and set the `$MY_DIR` environment variable to `/tmp`, it\nexpands to: `raftDir: /tmp`.\n\nBy default, the controller looks for configuration in `kubernetes-vault.yml` in the current working directory, but you\ncan override this by setting the `-config` flag with the absolute path to your config file.\n\nThe available configuration options in the config file are:\n\n#### raftDir *(optional)*\nThe location where raft data should be stored. By default this is: `/var/lib/kubernetes-vault/`.\n\nIf you want to set a custom location:\n```yaml\nraftDir: /my/custom/raft/dir\n```\n\n#### vault *(required)*\nSettings for communicating with the Vault server. It contains nested properties:\n\n* addr *(required)*\nThe address of the Vault server. For example, `http://vault:8200`.\n\n* token *(required)*\nA renewable and periodic Vault token to be used by the Kubernetes-Vault controller.\n\n* skipTokenRoleNameValidation *(optional)*\nIf set to `true` then skip validation for token role name. By default, this is: `false`.\n\n* tls *(optional)*\nIf Vault is secured using TLS (https), then you need to set one of the following:\n\n  * vaultCABackends *(optional)*\n    If Vault uses itself as a certificate authority, provide the list of root PKI backends here.\n\n  * caCert *(optional)*\n    If Vault uses an external CA, provide the absolute path to a file containing the CA certificates in PEM format.\n\n* wrappingTTL *(optional)*\nThe TTL for wrapped AppRole secret ids. By default, this is: `60s`.\n\n##### Example (using Vault as a CA):\n```yaml\nvault:\n  addr: http://vault:8200\n  token: 91526d9b-4850-3405-02a8-aa29e74e17a5\n  tls:\n    vaultCABackends:\n      - root-ca\n```\n\n#### kubernetes *(required)*\nSettings for talking to the Kubernetes API server.\n\n* watchNamespace *(required)*\nThe namespace to watch for newly created pods. If you want to watch for pods across multiple namespaces, you can prefix\n  it with `~` followed by a regex pattern. For example, using `~^(staging|default)$` will watch for pods in both the\n`staging` and `default` namespaces.\n\n  **IMPORTANT**: If you are using regex to watch multiple namespaces, make sure `vault.addr` is set to the FULL DNS name of\n  your Vault server. For example: `https://vault.default:8200` or `https://vault.staging:8200`. This is because the Vault\n  address is pushed to the watched pods, and those pods will only be able to communicate with pods outside their own\n  namespace using the FULL DNS name.\n\n* serviceNamespace *(required)*\nThe Kubernetes namespace the Kubernetes-Vault controller's service is in. This parameter and the `service` parameter\n  is used to discover other Kubernetes-Vault controllers to form a cluster.\n\n* service *(required)*\nThe Kubernetes service being used by the Kubernetes-Vault controller. Used in conjunction with `serviceNamespace` so\n  that it can discover other Kubernetes-Vault controllers to form a cluster.\n\n##### Example:\n```yaml\nkubernetes:\n  # For watchNamespace, you can use a regex by prefixing it with ~. For example: ~^(staging|default)$\n  watchNamespace: default\n  # Note the use of an environment variable here, which will be expanded by the controller\n  serviceNamespace: ${KUBERNETES_NAMESPACE}\n  service: kubernetes-vault\n```\n\n#### prometheus *(optional)*\nConfiguration for the Prometheus endpoint.\n\n* tls *(optional)*\nTLS configuration for the Prometheus endpoint. You can use Vault as the CA or an external CA. If using Vault as the CA,\n  you must set `vaultCertBackend`, `vaultCertRole`, `vaultCABackends`. Otherwise, set `certFile`, `certKey`, and `caCert`\nif using an external CA.\n\n  * vaultCertBackend *(optional)*\nThe Vault PKI backend to be used to issue certificates for securing the Prometheus metrics endpoint.\n\n  * vaultCertRole *(optional)*\nThe Vault PKI role to be used to issue certificates for securing the Prometheus metrics endpoint.\n\n  * vaultCABackends *(optional)*\nIf you want to enable client TLS authentication against the Prometheus scrappers, set the list of Vault PKI backend\n    being used as a certificate authority for those scrappers here.\n\n  * certFile *(optional)*\nIf using an external CA, provide the absolute path to the certificate in PEM format here.\n\n  * certKey *(optional)*\nIf using an external CA, provide the absolute path to the key for the certificate in PEM format here.\n\n  * caCert *(optional)*\nIf you want to enable client TLS authentication against the Prometheus scrappers, provide the absolute path to the file\n    containing the root certificates in PEM format here.\n\n##### Example:\n```yaml\nprometheus:\n  tls:\n    # Note that vaultCABackends is not set, so TLS client authentication for the scrappers will not be \n    # enabled.\n    vaultCertBackend: intermediate-ca\n    vaultCertRole: kubernetes-vault\n```\n\n### Init container configuration\nThe init containers are configured using environment variables and Kubernetes annotations.\n\n#### Environment variables\n\n| Environment Variable | Description                                                                                                                       | Required | Default Value                    | Example                                |\n|:---------------------|:----------------------------------------------------------------------------------------------------------------------------------|:---------|:---------------------------------|:---------------------------------------|\n| CREDENTIALS_PATH     | The location where the Vault token and CA Bundle (if it exists) will be written.                                                  | `no`     | `/var/run/secrets/boostport.com` | `/var/run/my/path`                     |\n| LOG_LEVEL            | The log level. Valid values are `debug` and `error`.                                                                              | `no`     | `debug`                          | `debug`                                |\n| RETRIEVE_TOKEN       | Whether to login using the `secret_id` and `role_id` to retrieve the auth token.                                                  | `no`     | `true`                           | `false`                                |\n| UNWRAP_SECRET        | Whether to unwrap the `secret_id`                                                                                                 | `no`     | `true`                           | `false`                                |\n| TIMEOUT              | Maximum amount of time to wait for the wrapped `secret_id` to be pushed. Valid time units are `ns`, `us`, `ms`, `s`, `m` and `h`. | `no`     | `5m`                             | `120s`                                 |\n| VAULT_ROLE_ID        | The Vault role id.                                                                                                                | `yes`    | `none`                           | `313b0821-4ff6-1df8-54dd-c3eea5d3b8b1` |\n\n#### Pod annotations\n\n| Annotation                             | Description                     | Required | Default Value | Example      |\n|:---------------------------------------|:--------------------------------|:---------|:--------------|:-------------|\n| pod.boostport.com/vault-approle        | The Vault role.                 | `yes`    | `none`        | `sample-app` |\n| pod.boostport.com/vault-init-container | The name of the init container. | `yes`    | `none`        | `install`    |\n\n## Metrics\nKubernetes-Vault uses [Prometheus](https://prometheus.io) for metrics reporting. It exposes these metrics over the `/metrics` endpoint over http or https.\n\nFor more information about metrics, read the guide on [metrics](metrics.md).\n\n## Sidekick container\n[UKHomeOffice/vault-sidekick](https://github.com/UKHomeOffice/vault-sidekick) is a sidekick container that runs in your pods\nto retrieve and renew credentials from Vault. The container has support for reading the token and other associated information\nfrom the token information that is created by the Kubernetes-Vault container.\n\nIn order to use `vault-sidekick` with Kubernetes-Vault, set the `AUTH_FILE` environment variable to the path of the token JSON\nfile written by the init container and the `AUTH_FORMAT` environment variable to `kubernetes-vault`.\n\n## Kubernetes version compatibility\n\n| Kubernetes Version    | Kubernetes-Vault Version |\n|:----------------------|:-------------------------|\n| \u003c= 1.5.x              | \u003c= 0.4.8                 |\n| \u003e= 1.6.x and \u003c= 1.7.x | any                      |\n| \u003e= 1.8.x              | \u003e= 0.5.0                 |\n\n## Troubleshooting\nSee the [troubleshooting guide](troubleshooting.md).\n\n## Development\nPRs are highly welcomed!\n\nWe use Go 1.11 and Go modules for dependency management.\n\nDocker is used to build the binaries, so you need to have docker installed.\n\nProduction images can be built using multi-stage docker builds by building the respective dockerfile in each binary's folder.\n\nFor development, simply run `build.sh` to build the binaries. To build the development docker images, run `build-dev-images.sh`.\nRunning `build-dev-images.sh` also automatically runs `build.sh`.\n\nThe `Dockerfile.dev` files are used to build development/testing images, while the `Dockerfile` files are used to build\nproduction images.\n\n## License\nThis project is licensed under the Apache 2 License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FBoostport%2Fkubernetes-vault","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FBoostport%2Fkubernetes-vault","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FBoostport%2Fkubernetes-vault/lists"}