From 20d532c3748b36518c8ae6f407e084a275d0ad6c Mon Sep 17 00:00:00 2001
From: Mikhail Fedosin <mfedosin@newrelic.com>
Date: Wed, 23 Aug 2023 18:33:23 +0200
Subject: [PATCH] Add v1alpha2 migration doc

---
 docs/migrating.md | 57 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 57 insertions(+)
 create mode 100644 docs/migrating.md

diff --git a/docs/migrating.md b/docs/migrating.md
new file mode 100644
index 000000000..1d270a4e1
--- /dev/null
+++ b/docs/migrating.md
@@ -0,0 +1,57 @@
+# Migrating from v1alpha1 to v1alpha2
+
+This document describes changes that were introduced in v1alpha2 API and how to update your templates to the new version.
+
+## ImageMeta -> imageURL conversion
+
+In v1alpha1 we use ImageMeta object that consists of 3 parts:
+
+- Repository (optional string): image registry (e.g., "example.com/repo")
+- Name (optional string): image name (e.g., "provider-image")
+- Tag (optional string): image tag (e.g., "v1.0.0")
+
+In v1alpha2 it is just a string, which represents the URL, e.g. `example.com/repo/image-name:v1.0.0`.
+
+Example:
+
+v1alpha1
+```yaml
+spec:
+ deployment:
+   containers:
+   - name: manager
+     image:
+       repository: "example.com/repo"
+       name: "image-name"
+       tag: "v1.0.0"
+```
+
+v1alpha2
+```yaml
+spec:
+ deployment:
+   containers:
+   - name: manager
+     imageURL: "example.com/repo/image-name:v1.0.0"
+```
+
+## secretName/secretNamespace -> configSecret conversion
+
+In v1alpha1 we have 2 separate top-level fields to point to a config secret: `secretName` and `secretNamespace`. In v1alpha2 we reworked them into an object `configSecret` that has 2 fields: `name` and `namespace`.
+
+Example:
+
+v1alpha1
+```yaml
+spec:
+ secretName: azure-variables
+ secretNamespace: capz-system
+```
+
+v1alpha2
+```yaml
+spec:
+ configSecret:
+   name: azure-variables
+   namespace: capz-system
+```