feat: add infrastructure and orchestrator diagrams (#13)

* feat: add infrastructure and orchestrator diagrams

* fix: diagrams

examples/dns/README.md

@@ -1,8 +1,7 @@
 # Example: dns resource based on GCP Cloud DNS
 
-This example configures a [dns](https://developer.humanitec.com/platform-orchestrator/reference/resource-types/#dns) Resource Definition using GCP Cloud DNS.
-
-The created Resource Definition can be used in your Score file using:
+## Configuration
+This example configures a [dns](https://developer.humanitec.com/platform-orchestrator/reference/resource-types/#dns) Resource Definition using GCP Cloud DNS. A workload using the `dns` resource to create dns records looks like:
 
 ```yaml
 containers:
@@ -22,6 +21,30 @@ resources:
       port: 3000
 ```
 
+## Infrastructure setup
+
+```mermaid
+graph TD;
+  subgraph GCP Managed zone
+    record["record"]
+  end
+
+  subgraph GKE Cluster
+    pod[workload pod]
+  end
+  record --> pod
+```
+
+## Orchestrator setup
+
+```mermaid
+graph LR;
+  workload_1 --> dns_1["dns_1, resource_type: dns"]
+  workload_2 --> dns_2["dns_2, resource_type: dns"]
+  workload_2 --> shared.dns_1["shared.dns_1, resource_type: dns"]
+  workload_3 --> shared.dns_1["shared.dns_1, resource_type: dns"]
+```
+
 <!-- BEGIN_TF_DOCS -->
 ## Requirements
 

examples/gcp-pubsub/README.md

@@ -1,9 +1,8 @@
 # Example: gcp-pubsub resource based on Google Cloud Pub/Sub
 
+## Configuration
 This example configures a [gcp-pubsub-topic](https://developer.humanitec.com/platform-orchestrator/reference/resource-types/#gcp-pubsub-topic) and a [gcp-pubsub-subscription](https://developer.humanitec.com/platform-orchestrator/reference/resource-types/#gcp-pubsub-subscription) Resource Definition using Google Cloud Pub/Sub.
 
-The Resource Graph is using [delegator resources](https://developer.humanitec.com/platform-orchestrator/examples/resource-graph-patterns/#delegator-resource) to expose shared resources with different access policies.
-
 Those Resource Definitions can be used in your Score file using:
 
 ```yaml
@@ -39,7 +38,41 @@ resources:
       topic_name: ${resources['gcp-pubsub-topic.basic#shared.main-topic'].outputs.name}
 ```
 
-The workload service account will automatically be assigned the necessary GCP Service Account with the selected role bindings.
+## Infrastructure setup
+The workload service account will be automatically assigned to the necessary roles with the selected policies.
+
+```mermaid
+graph TD;
+  topic["GCP Pub/Sub topic"]
+  sub["GCP Pub/Sub subscription"]
+  topic_account["GCP Service account"]
+  sub_account["GCP Service account"]
+  subgraph GKE Cluster
+    topic_pod[workload pod]
+    topic_service[Service Account]
+    sub_pod[workload pod]
+    sub_service[Service Account]
+  end
+  topic_service --> topic_account -- bind role on --> topic
+  topic_service --> topic_pod
+  topic --> topic_pod
+  sub_service --> sub_account -- bind role on --> sub
+  sub_service --> sub_pod
+  sub --> sub_pod
+  sub --> topic
+
+```
+
+## Orchestrator setup
+The Resource Graph is using [delegator resources](https://developer.humanitec.com/platform-orchestrator/examples/resource-graph-patterns/#delegator-resource) to expose shared resources with different access policies.
+
+```mermaid
+graph LR;
+  workload_1 --> delegator_1["delegator_1, resource_type: gcp-pubsub-topic", class: basic-publisher] --> shared.gcp-pubsub-topic_1["shared.gcp-pubsub-topic_1, resource_type: gcp-pubsub-topic"]
+  workload_2 --> delegator_2["delegator_2, resource_type: gcp-pubsub-subscriber, class: basic-consumer"] --> shared.gcp-pubsub-subscriber_1["shared.gcp-pubsub-subscriber_1, resource_type: gcp-pubsub-subscriber"]
+  workload_2 --> shared.delegator_1["shared.delegator_1, resource_type: gcp-pubsub-subscriber, class: basic-consumer"]
+  workload_3 --> shared.delegator_1 --> shared.gcp-pubsub-subscriber_2["shared.gcp-pubsub-subscriber_2, resource_type: gcp-pubsub-subscriber"]
+```
 
 <!-- BEGIN_TF_DOCS -->
 ## Requirements

examples/gcs/README.md

@@ -1,5 +1,6 @@
 # Example: gcs resource based on Google Cloud Storage
 
+## Configuration
 This example configures a [gcs](https://developer.humanitec.com/platform-orchestrator/reference/resource-types/#gcs) Resource Definition using Google Cloud Storage, with two different access policies:
 
 * `basic-admin` (full access)
@@ -20,9 +21,31 @@ resources:
     class: basic-admin
 ```
 
+## Infrastructure setup
+The workload service account will be automatically assigned to the necessary role with the selected policy.
+
+```mermaid
+graph TD;
+  gcs["Google Cloud Storage"]
+  subgraph GKE Cluster
+    pod[workload pod]
+    service[Service Account]
+  end
+  service -- bind role on --> gcs
+  service --> pod
+  gcs --> pod
+```
+
+## Orchestrator setup
 The Resource Graph is using [delegator resources](https://developer.humanitec.com/platform-orchestrator/examples/resource-graph-patterns/#delegator-resource) to expose shared resources with different access policies.
 
-The workload service account will automatically be assigned the necessary GCP Service Account with the selected role bindings.
+```mermaid
+graph LR;
+  workload_1 --> delegator_1["delegator_1, resource_type: gcs", class: basic-read-only] --> shared.gcs_1["shared.gcs_1, resource_type: gcs"]
+  workload_2 --> delegator_2["delegator_2, resource_type: gcs, class: basic-admin"] --> shared.gcs_1
+  workload_2 --> shared.delegator_1["shared.delegator_1, resource_type: gcs, class: basic-read-only"]
+  workload_3 --> shared.delegator_1 --> shared.gcs_2["shared.gcs_2, resource_type: gcs"]
+```
 
 <!-- BEGIN_TF_DOCS -->
 ## Requirements

examples/mysql/README.md

@@ -1,8 +1,7 @@
 # Example: mysql resource based on GCP CloudSQL
 
-This example configures a [mysql](https://developer.humanitec.com/platform-orchestrator/reference/resource-types/#mysql) Resource Definition using GCP CloudSQL.
-
-The created Resource Definition can be used in your Score file using:
+## Configuration
+This example configures a [mysql](https://developer.humanitec.com/platform-orchestrator/reference/resource-types/#mysql) Resource Definition using GCP CloudSQL. A workload using the `mysql` resource to create database instance looks like:
 
 ```yaml
 containers:
@@ -20,6 +19,29 @@ resources:
     type: mysql
 ```
 
+## Infrastructure setup
+
+```mermaid
+graph TD;
+  subgraph VPC
+    database["MySQl GCP CloudSQL"]
+    subgraph GKE Cluster
+      pod[workload pod]
+    end
+    database --> pod
+  end
+```
+
+## Orchestrator setup
+
+```mermaid
+graph LR;
+  workload_1 --> db_1["db_1, resource_type: mysql"]
+  workload_2 --> db_2["db_2, resource_type: mysql"]
+  workload_2 --> shared.db_1["shared.db_1, resource_type: mysql"]
+  workload_3 --> shared.db_1["shared.db_1, resource_type: mysql"]  
+```
+
 <!-- BEGIN_TF_DOCS -->
 ## Requirements
 
@@ -63,6 +85,6 @@ resources:
 | region | GCP region | `string` | n/a | yes |
 | name | Name of the example application | `string` | `"hum-rp-mysql-example"` | no |
 | prefix | Prefix of the created resources | `string` | `"hum-rp-mysql-ex-"` | no |
-| resource\_packs\_gcp\_rev | n/a | `string` | `"ref/heads/main"` | no |
+| resource\_packs\_gcp\_rev | n/a | `string` | `"refs/heads/main"` | no |
 | resource\_packs\_gcp\_url | n/a | `string` | `"https://github.com/humanitec-architecture/resource-packs-gcp.git"` | no |
 <!-- END_TF_DOCS -->

examples/mysql/terraform.tfvars.example

@@ -16,5 +16,5 @@ project = ""
 # GCP region
 region = ""
 
-resource_packs_gcp_rev = "ref/heads/main"
+resource_packs_gcp_rev = "refs/heads/main"
 resource_packs_gcp_url = "https://github.com/humanitec-architecture/resource-packs-gcp.git"

examples/mysql/variables.tf

@@ -6,7 +6,7 @@ variable "name" {
 
 variable "resource_packs_gcp_rev" {
   type    = string
-  default = "ref/heads/main"
+  default = "refs/heads/main"
 }
 
 variable "resource_packs_gcp_url" {

examples/postgres/README.md

@@ -1,8 +1,7 @@
 # Example: postgres resource based on GCP CloudSQL
 
-This example configures a [postgres](https://developer.humanitec.com/platform-orchestrator/reference/resource-types/#postgres) Resource Definition using GCP CloudSQL.
-
-The created Resource Definition can be used in your Score file using:
+## Configuration
+This example configures a [postgres](https://developer.humanitec.com/platform-orchestrator/reference/resource-types/#postgres) Resource Definition using GCP CloudSQL. A workload using the `postgres` resource to create database instance looks like:
 
 ```yaml
 containers:
@@ -20,6 +19,29 @@ resources:
     type: postgres
 ```
 
+## Infrastructure setup
+
+```mermaid
+graph TD;
+  subgraph VPC
+    database["Postgres GCP CloudSQL"]
+    subgraph GKE Cluster
+      pod[workload pod]
+    end
+    database --> pod
+  end
+```
+
+## Orchestrator setup
+
+```mermaid
+graph LR;
+  workload_1 --> db_1["db_1, resource_type: mysql"]
+  workload_2 --> db_2["db_2, resource_type: mysql"]
+  workload_2 --> shared.db_1["shared.db_1, resource_type: mysql"]
+  workload_3 --> shared.db_1["shared.db_1, resource_type: mysql"]  
+```
+
 <!-- BEGIN_TF_DOCS -->
 ## Requirements
 
@@ -63,6 +85,6 @@ resources:
 | region | GCP region | `string` | n/a | yes |
 | name | Name of the example application | `string` | `"hum-rp-postgres-example"` | no |
 | prefix | Prefix of the created resources | `string` | `"hum-rp-postgres-ex-"` | no |
-| resource\_packs\_gcp\_rev | n/a | `string` | `"ref/heads/main"` | no |
+| resource\_packs\_gcp\_rev | n/a | `string` | `"refs/heads/main"` | no |
 | resource\_packs\_gcp\_url | n/a | `string` | `"https://github.com/humanitec-architecture/resource-packs-gcp.git"` | no |
 <!-- END_TF_DOCS -->

examples/postgres/main.tf

@@ -20,6 +20,8 @@ resource "google_compute_global_address" "private_ip_address" {
   network       = data.google_compute_network.network.id
 }
 
+# There is a bug 
+# walkaround `gcloud services vpc-peerings update --network=htc-ref-arch-vpc --ranges=hum-rp-mysql-ex-private-ip-address --service=servicenetworking.googleapis.com --force`
 resource "google_service_networking_connection" "private_vpc_connection" {
   network                 = data.google_compute_network.network.id
   service                 = "servicenetworking.googleapis.com"

examples/postgres/terraform.tfvars.example

@@ -16,5 +16,5 @@ project = ""
 # GCP region
 region = ""
 
-resource_packs_gcp_rev = "ref/heads/main"
+resource_packs_gcp_rev = "refs/heads/main"
 resource_packs_gcp_url = "https://github.com/humanitec-architecture/resource-packs-gcp.git"

examples/postgres/variables.tf

@@ -6,7 +6,7 @@ variable "name" {
 
 variable "resource_packs_gcp_rev" {
   type    = string
-  default = "ref/heads/main"
+  default = "refs/heads/main"
 }
 
 variable "resource_packs_gcp_url" {

examples/redis/basic/README.md

@@ -1,8 +1,7 @@
 # Example: redis resource based on GCP Memorystore
 
-This example configures a [redis](https://developer.humanitec.com/platform-orchestrator/reference/resource-types/#redis) Resource Definition using GCP Memorystore.
-
-The created Resource Definition can be used in your Score file using:
+## Configuration
+This example configures a [redis](https://developer.humanitec.com/platform-orchestrator/reference/resource-types/#redis) Resource Definition using GCP Memorystore. A workload using the `redis` resource to create redis cluster looks like:
 
 ```yaml
 containers:
@@ -20,6 +19,30 @@ resources:
     type: redis
 ```
 
+## Infrastructure setup
+
+```mermaid
+graph TD;
+  subgraph VPC
+    cache["GCP Memorystore"]
+
+    subgraph GKE Cluster
+      pod[workload pod]
+    end
+  end
+  cache --> pod
+```
+
+## Orchestrator setup
+
+```mermaid
+graph LR;
+  workload_1 --> cache_1["cache_1, resource_type: redis"]
+  workload_2 --> cache_2["cache_2, resource_type: redis"]
+  workload_2 --> shared.cache_1["shared.cache_1, resource_type: redis"]
+  workload_3 --> shared.cache_1["shared.cache_1, resource_type: redis"]
+```
+
 <!-- BEGIN_TF_DOCS -->
 ## Requirements