From e3de49fd33e472baf6b19425a37c5d7dd525bc7c Mon Sep 17 00:00:00 2001 From: Timon Borter Date: Mon, 8 Jul 2024 21:35:59 +0200 Subject: [PATCH] docs: add images depicting the architecture --- README.md | 50 ++++++++++++++++++-- docs/application-architecture.puml | 30 ++++++++++++ docs/switch-workflow.puml | 76 ++++++++++++++++++++++++++++++ 3 files changed, 152 insertions(+), 4 deletions(-) create mode 100644 docs/application-architecture.puml create mode 100644 docs/switch-workflow.puml diff --git a/README.md b/README.md index 5279832..4f4d25d 100644 --- a/README.md +++ b/README.md @@ -25,9 +25,29 @@
+## Target Architecture + +`propeller` is designed to seamlessly integrate with a specific application deployment architecture commonly used in modern environments: + +- **Containerized Applications:** Applications are deployed within a [Kubernetes](https://kubernetes.io/) cluster for scalability and efficient resource management. +- **PostgreSQL Database:** Data is persisted in a robust [PostgreSQL](https://www.postgresql.org/) database, known for its reliability and feature set. +- **Vault for Secrets Management:** Sensitive information like passwords and API keys are securely stored and managed within [Vault](https://www.hashicorp.com/products/vault) for enhanced security. +- **ArgoCD for GitOps Automation:** [ArgoCD](https://argoproj.github.io/cd/) is utilized for GitOps principles, enabling declarative management of infrastructure and applications through Git repositories. Importantly, ArgoCD can also manage the synchronization of secrets from Vault using plugins like [@postfinance/kubectl-vault_sync](https://github.com/postfinance/kubectl-vault_sync). + +### Visual Representation + +![Architecture](https://www.plantuml.com/plantuml/png/VP2nRi8m48PtFyKrB310QDKkKMG1OQ6b4XLLzqjoX0Z7jiuELLNrtHj722gGEjh_tVzzzinvPDysIjpvFJK4npfdr5u8TwYrHSO62jDOeqbx-1O000ii3XMRLfUPKORJrBAnf1Inb32OJXyNJtFn8uJjvh0YYB9Ld2rXez3l33VHgUPI6wL5A4e6d_lQaypMgpJkRsG4w23KtqEQmfa3Klu5lBGviIPFxgPwRgsg2_IrqQ4AhRqUuCfaoskX3soLX-sNBc3uRF9Hxt5qtLdyxxvgEg4R-uSR-z1oOiDa8eDO0g-eksrtdVNSSmh3EDum1RSuXhqnXr7uYn8zvkW8DiRvgilVre5UvkBYshzAY8u5ux7iiWIstZ11M1Oz1jAGz8C9l3DgjoC6HmMJTs96kcmRzGi0) + +Source. + +`propeller` can either run as a CronJob in Kubernetes, or as part of any scheduled pipeline within your CI/CD environment. + ## Configuration -Propeller relies on a configuration file and an environment variable to function correctly. +Propeller relies on a [configuration file](#configuration-file-yaml) and [environment variables](#vault-authentication-token-vault_token) to function correctly. + +Once you're done configuring, [initialize Vault](#initializing-vault-for-secret-management). +And that's it: Proceed to [rotate your secrets](#rotating-secrets). ### Configuration File (YAML) @@ -76,9 +96,13 @@ It creates the necessary structure within your Vault instance to securely store **Command Usage:** ```cookie -propeller init-vault +propeller init-vault [OPTIONS] ``` +#### Options + +#### Result + After running the command, the specified Vault path will contain a JSON secret with the following structure: ```json @@ -94,8 +118,26 @@ After running the command, the specified Vault path will contain a JSON secret w **Note that any previously present secrets in this path will be lost in the process!** -The "TBD" placeholders indicate that these values _must_ be filled once with the initial values before continuing the rotation process. +The "TBD" placeholders indicate that these values _must_ be filled once with the initial values before continuing the [rotation process](#rotating-secrets). -#### Example Result +**Screenshot of initialized Vault secret:** [![Initial Vault Structure](img/initial-vault-structure.png)](img/initial-vault-structure.png) + +### Rotating Secrets + +Once Vault has been initialized, you're ready to frequently rotate your database secrets. + +**Command Usage:** + +```cookie +propeller rotate [OPTIONS] +``` + +#### Options + +#### Sequence Diagram + +!["switch" Workflow](https://www.plantuml.com/plantuml/png/nLF1RjGm4BtxAmPnWKFLRWMNFQ2M8d7X02nmT-qXiUHuZ3tUYh_7cpJOHbQ4gfLwoMx6y-Qzl7c-YIm3fycA5ppYX70qzq4w5iBdkb76vnVu7CYZjHZWvTNLc_TlRvlJ7p9PRlifyX3myELJKxuD0zrzQ4lUMwCa6t92E684EcAeo_lw1LB4U7e4s0aX5PkZP2pwX2XIBzujolRm5NybZ0npFyxmWbtKpq-uo9Y_0_OhZyQskIMf0H_HOJZrPGirJU1bZ0yKT8kexCdQY3DWeRekW9MnjhBy_LVe8Ic5CHQbDQxloNUlDtbhMxRPIdUNwF1WM8srzy3qo7jEkYLSU_WMp33aKY1hAN6XU4pVyfCHRSWElvqglTNH2jXKLHE82lp44BRI5gywtzyGjR6w8-TGCMJpnsBsTgPQtdN6F1qZotjhueYw7xAw-lGxVIs49V9vhhMG71kxhX4KJTxYQLO0DXFcMc__nUSLc9LpYjqOTBOwDyChZquRDrp6PSkNFwMng5ztjetkVs_txfbkz-vSjxjKIh-uGQVJPFy0) + +Source. diff --git a/docs/application-architecture.puml b/docs/application-architecture.puml new file mode 100644 index 0000000..c202ad7 --- /dev/null +++ b/docs/application-architecture.puml @@ -0,0 +1,30 @@ +@startuml + +!theme vibrant + +skinparam component { + BackgroundColor<> #004B5A +} + +package "CI/CD Platform" { + component "CLI" as prop1 << propeller >> +} + +package Kubernetes { + component Application as app + component ArgoCD + component "Vault Sync (Job)" as vsync + + component "Image" as prop2 << propeller >> + + ArgoCD ..> app: Manages + ArgoCD ..> vsync: Manages (//PreSync// hook) +} + +database PostgreSQL as db +component Vault + +app --> db: Store data +vsync <--> Vault: Transfer secrets + +@enduml diff --git a/docs/switch-workflow.puml b/docs/switch-workflow.puml new file mode 100644 index 0000000..deb7438 --- /dev/null +++ b/docs/switch-workflow.puml @@ -0,0 +1,76 @@ +@startuml + +!theme vibrant + +participant Propeller #004B5A +participant Vault +participant PostgreSQL +participant ArgoCD +participant Application + +note over Application: Application uses user 1 + +activate Propeller + +Propeller -> Vault: Request active user +activate Vault +Vault --> Propeller: user 1 +deactivate Vault + +Propeller -> Propeller: Generate random password + +Propeller -> PostgreSQL: Rotate user 2 password +activate PostgreSQL +PostgreSQL --> Propeller: Success +deactivate PostgreSQL + +Propeller -> Vault: Update user 2 password +activate Vault +Vault --> Propeller: Success +deactivate Vault + +Propeller -> Vault: Switch active user to user 2 +activate Vault +Vault --> Propeller: Success +deactivate Vault + +Propeller -> ArgoCD: Trigger rollout +activate ArgoCD +ArgoCD -> Application: Sync +activate Application +ArgoCD --> Propeller: Success +deactivate ArgoCD + +Application -> Vault: Request active user +activate Vault +Vault --> Application: user 2 +deactivate Vault + +Application -> PostgreSQL: Connect with user 2 +activate PostgreSQL +PostgreSQL --> Application: Connection established +deactivate PostgreSQL +deactivate Application + +note over Application: Application uses user 2 + +loop Poll until rollout complete or timeout +Propeller -> ArgoCD: Request rollout status +activate ArgoCD +ArgoCD --> Propeller: Status (pending/success/failed) +deactivate ArgoCD +end + +Propeller -> PostgreSQL: Rotate user 1 password +activate PostgreSQL +PostgreSQL --> Propeller: Success +deactivate PostgreSQL + +Propeller -> Vault: Update user 1 password +activate Vault +Vault --> Propeller: Success +deactivate Vault + +deactivate Propeller + +@enduml