added docs

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

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"

template_args.yaml

@@ -0,0 +1 @@
+last_insert_quantity: 3