From 32050e7bbfa9bc976be4018d6a79e7ceebebba81 Mon Sep 17 00:00:00 2001 From: Eugene Davis Date: Tue, 7 Jun 2022 15:35:59 +0200 Subject: [PATCH] Rename Project and Improve Docs (#19) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * add config examples * Updates to docs * Update name * Bump version: 0.3.4 → 0.3.5 * Version check fix --- .bumpversion.cfg | 2 +- .github/workflows/pr-checks.yml | 10 ++-- .github/workflows/release.yml | 2 +- README.md | 47 ++++++++++++++-- docs/CONFIGURATION_EXAMPLES.md | 72 +++++++++++++++++++++++++ pyproject.toml | 4 +- vault_monitor/scripts/start_exporter.py | 2 +- 7 files changed, 126 insertions(+), 13 deletions(-) create mode 100644 docs/CONFIGURATION_EXAMPLES.md diff --git a/.bumpversion.cfg b/.bumpversion.cfg index 6588932..cf130ee 100644 --- a/.bumpversion.cfg +++ b/.bumpversion.cfg @@ -1,5 +1,5 @@ [bumpversion] -current_version = 0.3.4 +current_version = 0.3.5 commit = True tag = False message = Bump version: {current_version} → {new_version} diff --git a/.github/workflows/pr-checks.yml b/.github/workflows/pr-checks.yml index dc67bc5..5302b20 100644 --- a/.github/workflows/pr-checks.yml +++ b/.github/workflows/pr-checks.yml @@ -106,8 +106,8 @@ jobs: run: poetry install - name: Get current version - id: current-version - run: echo "::set-output name=version::$(poetry run bump2version --list --dry-run patch | grep current_version= | sed -r s,"^.*=",,)" + id: current_version + run: echo "::set-output name=version::$(poetry version | cut -d" " -f2)" - name: Checkout ${{ github.base_ref }} uses: actions/checkout@v2 @@ -115,11 +115,11 @@ jobs: ref: ${{ github.base_ref }} - name: Get ${{ github.base_ref }} version - id: old-version + id: old_version run: | - echo "::set-output name=version::$(poetry run bump2version --dry-run --no-configured-files --list --allow-dirty patch | grep current_version= | sed -r s,"^.*=",,)" + echo "::set-output name=version::$(poetry version | cut -d" " -f2)" - name: Checkout current branch uses: actions/checkout@v2 - name: Check version has been bumped - run: "python .github/workflows/version_check.py --current-branch ${{ steps.current-version.outputs.version }} --target-branch ${{ steps.old-version.outputs.version }}" + run: "python .github/workflows/version_check.py --current-branch ${{ steps.current_version.outputs.version }} --target-branch ${{ steps.old_version.outputs.version }}" diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 61d77ed..b3eabcf 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -6,7 +6,7 @@ on: workflow_dispatch: env: - VERSION: 0.3.4 + VERSION: 0.3.5 jobs: docker: diff --git a/README.md b/README.md index a82b06b..1bb702c 100644 --- a/README.md +++ b/README.md @@ -1,15 +1,56 @@ -# Vault Monitor Exporter +# Vault Assesment Prometheus Exporter [![PR Checks](https://github.com/tomtom-internal/sp-devsup-vault-expiration-monitoring/actions/workflows/pr-checks.yml/badge.svg)](https://github.com/tomtom-internal/sp-devsup-vault-expiration-monitoring/actions/workflows/pr-checks.yml) [![security: bandit](https://img.shields.io/badge/security-bandit-yellow.svg)](https://github.com/PyCQA/bandit) Provides a prometheus exporter for monitoring aspects of a running HashiCorp Vault server. -## Deploy +At the moment, the sole focus is on monitoring KV2 static secrets for expiration based on custom metadata, however it has been designed with the intent to allow modular creation of additional monitors, e.g. for monitoring other types of secrets engines or authentication types for rotation needs, or for other at-a-glance metrics. + +## Deploying Vault Assesment Prometheus Exporter + +## Vault Configuration + +Before deploying the exporter, you will need to configure access for it into Vault. + +### Supported Authentication methods + +The exporter supports three authentication methods: + +* [token](https://www.vaultproject.io/docs/internals/token) (intended primarily for development) +* [approle](https://www.vaultproject.io/docs/auth/approle) +* [kubernetes](https://www.vaultproject.io/docs/auth/kubernetes) + +Additional authentication methods should be relatively easy to add due to usage of the [hvac](https://hvac.readthedocs.io/en/stable/overview.html) module, please feel free to open an issue or a pull request with any you might need. + +### Policy + +The exporter requires the `read` capability access to the metadata of the monitored secrets. Additionally, if you are using the recursive function to monitor multiple secrets in a path, you will need to provide the `list` capability. + +A sample policy for a secret in the KV2 engine `secret` at path `some/example/secret` would need a policy like: + +```hcl +path "secret/metadata/some/example/secret" { + capabilities = [ "read" ] +} +``` + +To recursively monitor at the `example` level, it would look like: + +```hcl +path "secret/metadata/some/example/**" { + capabilities = [ "read", "list" ] +} +``` + +### Docker Image + +A Docker image can be found on Dockerhub at `tomtomcom/vault-expiration-monitor`. +The location of the secret file can be set with the `CONFIG_FILE` environmental variable, any other environment variables that may be required (e.g. for approles) are based on configuration. ### Direct Installation -At present, the easiest method to install and run is to use [poetry](https://python-poetry.org/). +To install and run locally, use [poetry](https://python-poetry.org/). To install and run, do the following: 1. `poetry install` diff --git a/docs/CONFIGURATION_EXAMPLES.md b/docs/CONFIGURATION_EXAMPLES.md new file mode 100644 index 0000000..33e3690 --- /dev/null +++ b/docs/CONFIGURATION_EXAMPLES.md @@ -0,0 +1,72 @@ +# Configuration Examples + +## Basic Configuration - Simple + +At a bare minimum, Vault must be configured with an address and some authentication method + +```yaml +vault: + address: https://vault.exampledomainname.com + authentication: + token: +``` + +## Complete Simple Configuration using Token Authentication for Expiration Monitoring + +An example of the absolute bare minimum configuration to monitor a single secret. + +```yaml +vault: + address: https://vault.exampledomainname.com + authentication: + token: + +secret_expiration_monitoring: + - name: simple_service + secrets: + - mount_point: secrets + secret_path: expiring_secrets +``` + +## Complete Complex Configuration for Expiration Monitoring + +Uses all non-exclusive settings for monitoring a secret. + +```yaml +vault: + address: https://vault.exampledomainname.com + namespace: thenamespace # optional, don't set for root/open source + # If multiple options are set, goes approle, kubernetes, token + authentication: + # Configuration for approle + approle: + mount_point: someapproleauth # default approle + role_id: ab462-0462ac + secret_id_variable: VAULT_MONITOR_SECRET_ID # the associated environmental variable must be set + + +refresh_interval: 10 # default is 30 seconds +port: 8350 # default is 9935 + +secret_expiration_monitoring: + metadata_fieldnames: + last_renewal_timestamp: "first_last_renewal_timestamp" # default is last_renewal_timestamp + expiration_timestamp: "first_expiration_timestamp" # default is expiration_timestamp + prometheus_labels: # Global configuration for prometheus labels + team: tomtom + environment: prod + owner: Eugene Davis + services: + - name: complicated_service + # Allow overriding the default labels - must *update* the existing defaults (optional) + prometheus_labels: + environment: dev # Cannot add a key that doesn't already exist in the global configuration + secrets: + - mount_point: secrets + secret_path: expiration_secrets + recursive: True # Require the list permission, but be able to monitor every sub-secret (optional, default False) + + metadata_fieldnames: # Allow overriding the defaults per-service (optional) - the earlier configured fieldnames will be ignored for this service + last_renewal_timestamp: "some_last_renewal_timestamp" + expiration_timestamp: "some_expiration_timestamp" +``` diff --git a/pyproject.toml b/pyproject.toml index 149299d..996e454 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,6 +1,6 @@ [tool.poetry] -name = "sp-devsup-vault-expiration-monitoring" -version = "0.3.4" +name = "vault-assesment-prometheus-exporter" +version = "0.3.5" description = "Prometheus exporter to monitor custom metadata for KV2 secrets for (self-imposed) expiration." authors = ["Eugene Davis "] readme = "README.md" diff --git a/vault_monitor/scripts/start_exporter.py b/vault_monitor/scripts/start_exporter.py index b0129a4..344daa6 100644 --- a/vault_monitor/scripts/start_exporter.py +++ b/vault_monitor/scripts/start_exporter.py @@ -1,5 +1,5 @@ """ -Launches the vault monitoring exporter +Launches Vault Assesment Prometheus Exporter """ import sys import logging