Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

add images depicting the architecture #11

Merged
merged 1 commit into from
Jul 9, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
50 changes: 46 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,9 +25,29 @@

<hr>

## 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)

<small><a href="./docs/application-architecture.puml">Source</a>.</small>

`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)

Expand Down Expand Up @@ -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
Expand All @@ -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)

<small><a href="./docs/switch-workflow.puml">Source</a>.</small>
30 changes: 30 additions & 0 deletions docs/application-architecture.puml
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
@startuml

!theme vibrant

skinparam component {
BackgroundColor<<propeller>> #004B5A
}

package "CI/CD Platform" {
component "<color:#white>CLI</color>" as prop1 << propeller >>
}

package Kubernetes {
component Application as app
component ArgoCD
component "Vault Sync (Job)" as vsync

component "<color:#white>Image</color>" 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
76 changes: 76 additions & 0 deletions docs/switch-workflow.puml
Original file line number Diff line number Diff line change
@@ -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
Loading