From 831b3c91cc8517b4cac8543e5b4427dafbde8b1f Mon Sep 17 00:00:00 2001
From: Gyanendra Mishra <anomaly.the@gmail.com>
Date: Tue, 20 Aug 2024 13:39:10 +0000
Subject: [PATCH] added docs

---
 README.md          | 26 ++++++++++++++++++++++++++
 template.yaml      | 35 +++++++++++++++++++++++++++++++++++
 template_args.yaml |  1 +
 3 files changed, 62 insertions(+)
 create mode 100644 template.yaml
 create mode 100644 template_args.yaml

diff --git a/README.md b/README.md
index 4d1a404..9fa87ee 100644
--- a/README.md
+++ b/README.md
@@ -116,6 +116,32 @@ Follow these steps to explore the Kardinal Playground.
 
 This guide showcases the power of Kardinal by demonstrating the seamless creation and deletion of a dev environment alongside your main, stable setup. You'll experience firsthand how Kardinal enables isolated development without risking stability of a shared cluster, or disrupting the live environment. 🚀
 
+## 🧠 Advanced
+
+Kardinal also has supports for `templates`. Templates are overrides on the base manifest that allow you to configure annotations different from the base manifest.
+[Template Example](/template.yaml) is one such template that does the following
+
+1. It adds an extra item to the database compared to the base manifest and it shows how the quantity field is configurable; when used with [example arguments file](/template_args.yaml) an extra item in the cart with quantity set to 3. If you don't supply args it defaults to 1.
+1. It adds an extra annotation `kardinal.dev.service/shared: "true"`. Any flow using this template uses a `shared` instance of Postgres allowing you to use the same instance across flows; making it more resource efficient.
+
+While the plugin annotation replaces any existing plugin annotation on the Postgres service; the `shared` annotation is additive to the base manifest.
+
+To create a template use the following command
+
+```bash
+kardinal tempalte create extra-item-shared --template-yaml ./template.yaml --description "Extra item and postgres is shared"
+```
+
+You can use the alias `-t` for the `--template-yaml` flag and `-d` for the `--description` flag.
+
+To use the template with a flow
+
+```bash
+kardinal flow create frontend kurtosistech/frontend:demo-frontend  --template-args ./template_args.yaml --template extra-item-shared
+```
+
+You can use the alias `-a` for the `--template-args` flag and `-t` for the `--template` flag.
+
 ## 🔗 Port Forwarding Explanation
 
 We're using port forwarding in combination with a proxy in this Codespace setup to make the various services accessible to you. We use Codespaces to forward URLs over the internet but add an nginx proxy to set the right hostname to hit the right lightweight environment
diff --git a/template.yaml b/template.yaml
new file mode 100644
index 0000000..24bc9fa
--- /dev/null
+++ b/template.yaml
@@ -0,0 +1,35 @@
+apiVersion: v1
+kind: Service
+metadata:
+  name: postgres
+  annotations:
+    kardinal.dev.service/shared: "true"
+    kardinal.dev.service/plugins: |
+      - name: github.com/kurtosis-tech/postgres-seed-plugin
+        args:
+          seed_script: |
+            --  create the table
+            CREATE TABLE IF NOT EXISTS public.items(
+                id bigserial PRIMARY KEY,
+                created_at TIMESTAMP WITH TIME ZONE,
+                updated_at TIMESTAMP WITH TIME ZONE,
+                deleted_at TIMESTAMP WITH TIME ZONE,
+                user_id TEXT,
+                product_id TEXT,
+                quantity INTEGER
+            );
+
+            INSERT INTO public.items (id, created_at, updated_at, deleted_at, user_id, product_id, quantity) 
+            VALUES (1, '2024-08-02 13:02:07.656104 +00:00', '2024-08-02 13:02:07.656104 +00:00', null, '0494c5e0-dde0-48fa-a6d8-f7962f5476bf', '66VCHSJNUP', 1);
+
+            INSERT INTO public.items (id, created_at, updated_at, deleted_at, user_id, product_id, quantity) 
+            VALUES (2, '2024-08-02 13:02:10.891407 +00:00', '2024-08-02 13:02:10.891407 +00:00', null, '0494c5e0-dde0-48fa-a6d8-f7962f5476bf', '2ZYFJ3GM2N', 1);
+
+            INSERT INTO public.items (id, created_at, updated_at, deleted_at, user_id, product_id, quantity) 
+            VALUES (3, '2024-08-02 13:03:10.891407 +00:00', '2024-08-02 13:02:10.891407 +00:00', null, '0494c5e0-dde0-48fa-a6d8-f7962f5476bf', '2ZYFJ3GM2N', ${last_insert_quantity:-1});
+
+            -- Set the sequence to the correct value after inserting records
+            SELECT setval('public.items_id_seq', (SELECT MAX(id) FROM public.items));
+          db_name: "cart"
+          db_user: "postgresuser"
+          db_password: "postgrespass"
\ No newline at end of file
diff --git a/template_args.yaml b/template_args.yaml
new file mode 100644
index 0000000..de2ea28
--- /dev/null
+++ b/template_args.yaml
@@ -0,0 +1 @@
+last_insert_quantity: 3