Rename Project and Improve Docs (#19)

* add config examples

* Updates to docs

* Update name

* Bump version: 0.3.4 → 0.3.5

* Version check fix

.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}

.github/workflows/pr-checks.yml

@@ -106,20 +106,20 @@ 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
       with:
         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 }}"

.github/workflows/release.yml

@@ -6,7 +6,7 @@ on:
   workflow_dispatch:
 
 env:
-  VERSION: 0.3.4
+  VERSION: 0.3.5
 
 jobs:
   docker:

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`

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"
+```

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 <[email protected]>"]
 readme = "README.md"

vault_monitor/scripts/start_exporter.py

@@ -1,5 +1,5 @@
 """
-Launches the vault monitoring exporter
+Launches Vault Assesment Prometheus Exporter
 """
 import sys
 import logging