docs: add examples (#87)

.licensei.toml

@@ -35,7 +35,7 @@ ignored = [
 
 [header]
 authors = ["Cisco"]
-ignorePaths = [".direnv", ".devenv", "vendor"]
+ignorePaths = [".direnv", ".devenv", "vendor", "examples"]
 ignoreFiles = ["zz_generated.*.go"]
 template = """// Copyright © :YEAR: :AUTHOR:
 //

README.md

@@ -10,8 +10,6 @@
 
 **Secret Sync** exposes a generic way to interact with external secret storage systems like [HashiCorp Vault](https://www.vaultproject.io/) and provides a set of API models to interact and orchestrate the synchronization of secrets between them.
 
-This name was chosen in a rush, we are open to naming suggestions 😄
-
 > [!IMPORTANT]
 > This is an **early alpha version** and breaking changes are expected.
 > As such, it is not recommended for usage in production.
@@ -27,40 +25,32 @@ This name was chosen in a rush, we are open to naming suggestions 😄
 - Advanced templating capabilities for transforming secrets
 
 | **Supported store**                                                      | **Status** |
-|--------------------------------------------------------------------------|--------|
-| [HashiCorp Vault](https://www.vaultproject.io)                           | alpha  |
-| [Local Provider](#secret-store)                                          | alpha  |
-| [AWS Secrets Manager](https://aws.amazon.com/secrets-manager)            | _planned_ |
-| [Google Secrets Manager](https://cloud.google.com/secret-manager)        | _planned_ |
-| [Azure Key Vault](https://azure.microsoft.com/en-us/services/key-vault/) | _planned_ |
-| [Kubernetes Secret](https://kubernetes.io/)                              | _planned_ |
+|--------------------------------------------------------------------------|------------|
+| [HashiCorp Vault](https://www.vaultproject.io)                           | alpha      |
+| [Local Provider](#secret-store)                                          | alpha      |
+| [AWS Secrets Manager](https://aws.amazon.com/secrets-manager)            | _planned_  |
+| [Google Secrets Manager](https://cloud.google.com/secret-manager)        | _planned_  |
+| [Azure Key Vault](https://azure.microsoft.com/en-us/services/key-vault/) | _planned_  |
+| [Kubernetes Secret](https://kubernetes.io/)                              | _planned_  |
 
 Check details about upcoming features by visiting the [project issue](https://github.com/bank-vaults/secret-sync/issues) board.
 
 ## Goals
 
 * Provide safe and simple way to work with secrets
-* Common API for secret management regardless of the store backend
-* Explicit control over the secret synchronization process
+* Expose common API for secret management regardless of the store backend
+* Give total control of the secret synchronization process
 
 > Consider a situation where Dev teams need access to secrets from different environments.
-> Ops teams can provide access to secrets in the form of a sandboxed environment (e.g. new Vault instance) synced only with secrets Devs require; all in GitOps way.
-
-## Getting Started
-
-To get familiarized, we will show how you can use these tools to answer two questions:
-
-- **Ops**: How do I synchronize secrets from one secret storage systems to another?
-- **Dev**: How do I consume secrets to bootstrap my application?
+> Ops teams can provide access to secrets in the form of an isolated environment (e.g. new Vault instance) synced only with secrets Devs require; all in GitOps way.
 
-To answer the first question, we shall create some database secrets and synchronize them into Vault.<br>
-For the second question, we will use some secrets from Vault to create an access file for an application.
+## Getting started
 
-You can find complete examples and instructions in the [EXAMPLE](EXAMPLE.md) file.
+To get familiarized, check out the collection of different [examples](examples) using this tool.
 
 ## Documentation
 
-Check out the documentation at [API documentation](docs/API.md) page or on [pkg.go.dev](https://pkg.go.dev/mod/github.com/bank-vaults/secret-sync).
+Check out the [project documentation](docs) or [pkg.go.dev](https://pkg.go.dev/mod/github.com/bank-vaults/secret-sync).
 
 ## Development
 

docs/API.md

@@ -13,8 +13,6 @@ secretsStore:
   storeName: storeSpec
 ```
 
-You can find all the Secret Store specifications in [pkg/apis/v1alpha1/secretstore.go](pkg/apis/v1alpha1/secretstore.go)
-
 <details>
 <summary>Store Spec: <b>HashiCorp Vault*</b></summary>
 
@@ -68,8 +66,6 @@ sync:
   - actionSpec
 ```
 
-You can find all the Sync Plan specifications in [pkg/apis/v1alpha1/syncjob_types.go](pkg/apis/v1alpha1/syncjob_types.go)
-
 <details>
 <summary>Action Spec: <b>Synchronize a secret from reference</b></summary>
 
@@ -302,5 +298,5 @@ Note that only YAML configuration files are supported.
 You can also provide optional params for CRON schedule to periodically sync secrets via `--schedule` flag.
 All sync actions are indexed in logs based on their order in the sync plan config file.
 
-You can also use [pkg/storesync](pkg/storesync) package to run secret synchronization plan natively from Golang.
+You can also use [pkg/storesync](https://pkg.go.dev/github.com/bank-vaults/secret-sync/pkg/storesync) package to run secret synchronization plan natively from Golang.
 This is how the CLI works as well.

docs/README.md

@@ -0,0 +1,5 @@
+## Documentation
+
+Here you can find documentation about the way **Secret Sync** works. Refer to:
+
+- [API](API.md) - Documentation on how to use different secret stores, synchronization policies, and templating rules.

examples/README.md

@@ -0,0 +1,5 @@
+## Usage Examples
+
+Here you can find various examples on how you can use **Secret Sync**. Examples include:
+
+- [single-source-advanced](single-source-advanced) - Use a central source of truth to synchronize secrets into different secret stores. Uses templating for fine-grained synchronization.

examples/assets/gen-assets.sh

@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+
+# Requirement: https://github.com/terrastruct/d2
+
+ASSET_DIR=$( cd -- "$( dirname -- "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )
+
+for d2_file in "$ASSET_DIR"/*.d2
+do
+  # Get files
+  png_file=${d2_file%".d2"}.png
+
+  # Generate PNG from diagram
+  d2 $d2_file $png_file
+done

examples/assets/native-approach.d2

@@ -0,0 +1,42 @@
+direction: down
+
+Vault: {
+  label: Vault
+  shape: image
+  icon: https://www.svgrepo.com/download/448679/vault.svg
+}
+
+AWSSM: {
+  label: AWS Secrets Manager
+  shape: image
+  icon: https://icons.terrastruct.com/aws%2FSecurity%2C%20Identity%2C%20&%20Compliance%2FAWS-Secrets-Manager.svg
+}
+
+GCPSM: {
+  label: GCP Secret Manager
+  shape: image
+  icon: https://www.svgrepo.com/download/375492/secret-manager.svg
+}
+
+AzureKeyVault: {
+  label: Azure Key Vault
+  shape: image
+  icon: https://icons.terrastruct.com/azure%2FSecurity%20Service%20Color%2FKey%20Vaults.svg
+}
+
+Cluster: {
+  label: Cluster
+  icon: https://icons.terrastruct.com/azure%2F_Companies%2FKubernetes.svg
+
+  Local: {
+    Label: Secret
+  }
+  Workload: Workload
+
+  Local -> Workload
+}
+
+Cluster.Local <- Vault
+Cluster.Local <- AWSSM
+Cluster.Local <- GCPSM
+Cluster.Local <- AzureKeyVault

examples/assets/secret-sync.d2

@@ -0,0 +1,137 @@
+direction: down
+
+Vault: {
+  label: Vault
+  shape: image
+  icon: https://www.svgrepo.com/download/448679/vault.svg
+}
+
+AWSSM: {
+  label: AWS Secrets Manager
+  shape: image
+  icon: https://icons.terrastruct.com/aws%2FSecurity%2C%20Identity%2C%20&%20Compliance%2FAWS-Secrets-Manager.svg
+  style: {
+    opacity: 0.4
+  }
+}
+
+GCPSM: {
+  label: GCP Secret Manager
+  shape: image
+  icon: https://www.svgrepo.com/download/375492/secret-manager.svg
+  style: {
+    opacity: 0.4
+  }
+}
+
+AzureKeyVault: {
+  label: Azure Key Vault
+  shape: image
+  icon: https://icons.terrastruct.com/azure%2FSecurity%20Service%20Color%2FKey%20Vaults.svg
+  style: {
+    opacity: 0.4
+  }
+}
+
+BVSecretSync: {
+  label: Bank-Vaults Secret Sync
+  shape: image
+  icon: https://raw.githubusercontent.com/bank-vaults/bank-vaults.dev/main/assets/icons/logo.svg
+}
+
+Vault -> BVSecretSync
+AWSSM -> BVSecretSync {
+  style: {
+    opacity: 0.4
+  }
+}
+GCPSM -> BVSecretSync {
+  style: {
+    opacity: 0.4
+  }
+}
+AzureKeyVault -> BVSecretSync {
+  style: {
+    opacity: 0.4
+  }
+}
+
+ClusterA: {
+  label: Cluster A
+  icon: https://icons.terrastruct.com/azure%2F_Companies%2FKubernetes.svg
+
+  style: {
+    opacity: 0.4
+  }
+
+  LocalA: Secret {
+    style: {
+      opacity: 0.4
+    }
+  }
+  WorkloadA: Workload {
+      style: {
+        opacity: 0.4
+      }
+  }
+
+  LocalA -> WorkloadA {
+    style: {
+      opacity: 0.4
+    }
+  }
+}
+
+ClusterB: {
+  label: Cluster B
+  icon: https://icons.terrastruct.com/azure%2F_Companies%2FKubernetes.svg
+
+  LocalB: {
+    label: Local Vault
+    shape: image
+    width: 80
+    icon: https://www.svgrepo.com/download/448679/vault.svg
+  }
+  WorkloadB: Workload
+
+  LocalB -> WorkloadB
+}
+
+LocalC: {
+    label: Tenant Environment
+    shape: image
+    width: 80
+    icon: https://www.svgrepo.com/download/375492/secret-manager.svg
+    style: {
+      opacity: 0.4
+    }
+}
+
+ClusterC: {
+  label: Cluster C
+  icon: https://icons.terrastruct.com/azure%2F_Companies%2FKubernetes.svg
+
+  style: {
+    opacity: 0.4
+  }
+
+  WorkloadC: Workload {
+      style: {
+        opacity: 0.4
+      }
+  }
+}
+
+LocalC -> ClusterC.WorkloadC
+
+BVSecretSync -> ClusterB.LocalB: Sync
+BVSecretSync -> ClusterA.LocalA: Sync {
+  style: {
+    opacity: 0.4
+  }
+}
+BVSecretSync -> LocalC: Sync {
+  style: {
+    opacity: 0.4
+  }
+}