Add documentation

README.md

@@ -1,2 +1,30 @@
-# rotate-maps-api-key-workflow
-GitHub workflow for rotating Google Maps API keys
+# Google Maps API key rotation workflow
+
+This repository contains the actual workflow used to rotate the Google Maps API key and is automatically generated by [rotate-maps-api-key](https://github.com/streof/rotate-maps-api-key).
+
+# Introduction
+
+The aim of the workflow is to automate the process of rotating a Google Maps API key without disturbing services that rely on it. The API key is stored as a secret named GoogleMapKey in Azure Key Vault. More information on the infrastructure setup can be found in the parent repository.
+
+# Implementation
+
+The implementation assumes that consuming services do not cache the API key for more than 24 hours. The workflow runs daily at 2 AM UTC and consists of a single job `rotate-key` that executes the following steps:
+
+1. Checkout Repository
+2. Authenticate with Google Cloud
+3. Set up gcloud
+4. Create API key
+5. Authenticate with Azure
+6. Store in Azure Key Vault
+7. Delete old API keys
+
+The authentication steps use the official GitHub Actions for Azure and Google Cloud. The required credentials have been generated by the parent repository and are available as secrets.
+
+In step 4, an API key called _Google Maps API Key_ is created. The actual key is [masked](https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions#example-masking-a-generated-output-within-a-single-job) before making it available to the remaining steps of the job. Any sensitive output is suppressed.
+
+In step 6, the actual API key is stored under the name _GoogleMapKey_ in the Azure Key Vault, which creates a new version of the secret.
+
+The last steps deletes Google Maps API keys older than 24 hours.
+
+# Future work
+- Add a cleanup step that deletes older versions of the GoogleMapKey secret from the Azure Key Vault as is can [impact](https://learn.microsoft.com/en-us/azure/key-vault/general/service-limits#limits-on-count-of-keys-secrets-and-certificates) the performance of backup operations.