From 0791472b726e9b3557aa5e0a80f7dc8c9c5dcc43 Mon Sep 17 00:00:00 2001
From: unclegedd <gedd@defenseunicorns.com>
Date: Wed, 3 Apr 2024 10:26:02 -0500
Subject: [PATCH] chore: adds dup pkgs docs

---
 README.md | 47 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 47 insertions(+)

diff --git a/README.md b/README.md
index aa9ee465d..0a6758ce0 100644
--- a/README.md
+++ b/README.md
@@ -20,6 +20,7 @@
 1. [Bundle Architecture and Multi-Arch Support](#bundle-architecture-and-multi-arch-support)
 1. [Configuration](#configuration)
 1. [Sharing Variables](#sharing-variables)
+1. [Duplicate Packages and Naming](#duplicate-packages-and-naming)
 1. [Zarf Integration](#zarf-integration)
 1. [Bundle Overrides](docs/overrides.md)
 1. [Bundle Anatomy](docs/anatomy.md)
@@ -221,5 +222,51 @@ In a bundle, variables can come from 4 sources. Those sources and their preceden
 That is to say, variables set using the `--set` flag take precedence over all other variable sources.
 
 
+## Duplicate Packages And Naming
+
+It is possible to deploy multiple instances of the same Zarf package in a bundle. For example, the following `uds-bundle.yaml` deploys 3 instances of the [helm-overrides](src/test/packages/helm/zarf.yaml) Zarf packags:
+```yaml
+kind: UDSBundle
+metadata:
+   name: duplicates
+   description: testing a bundle with duplicate packages in specified namespaces
+   version: 0.0.1
+
+packages:
+   - name: helm-overrides
+     repository: localhost:5000/helm-overrides
+     ref: 0.0.1
+     overrides:
+        podinfo-component:
+           unicorn-podinfo: # name of Helm chart
+              namespace: podinfo-ns
+
+   # note the unique name and namespace
+   - name: helm-overrides-duplicate
+     repository: localhost:5000/helm-overrides
+     ref: 0.0.1
+     overrides:
+        podinfo-component:
+           unicorn-podinfo:
+              namespace: another-podinfo-ns
+
+     # note the unique name, namespace and the path to the Zarf package tarball
+   - name: helm-overrides-local-duplicate
+     path: src/test/packages/helm/zarf-package-helm-overrides-arm64-0.0.1.tar.zst
+     ref: 0.0.1
+     overrides:
+        podinfo-component:
+           unicorn-podinfo:
+              namespace: yet-another-podinfo-ns
+```
+
+The naming conventions for deploying duplicate packages are as follows:
+1. The `name` field of the package in the `uds-bundle.yaml` must be unique
+1. The duplicate packages must be deployed in different namespaces
+1. In order to deploy duplicates of local packages, the `path` field must point to a Zarf package tarball instead of to a folder; this allows us to satisfy the first convention.
+
+> [!NOTE]  
+> Today the duplicate packages feature is only supported for packages with Helm charts. This is because Helm charts [namespaces can be overridden](docs/overrides.md#namespace) at deploy time.
+
 ## Zarf Integration
 UDS CLI includes a vendored version of Zarf inside of its binary. To use Zarf, simply run `uds zarf <command>`. For example, to create a Zarf package, run `uds zarf create <dir>`, or to use the [airgap tooling](https://docs.zarf.dev/docs/the-zarf-cli/cli-commands/zarf_tools) that Zarf provides, run `uds zarf tools <cmd>`.