From ad20d90ea3518a3606b2d604ed1de64959a88db1 Mon Sep 17 00:00:00 2001
From: kurokobo <2920259+kurokobo@users.noreply.github.com>
Date: Sun, 6 Feb 2022 15:02:37 +0900
Subject: [PATCH] feat: add guide to use external database

---
 README.md           |   1 +
 tips/README.md      |   1 +
 tips/external-db.md | 122 ++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 124 insertions(+)
 create mode 100644 tips/external-db.md

diff --git a/README.md b/README.md
index e1148c5..5570706 100644
--- a/README.md
+++ b/README.md
@@ -432,6 +432,7 @@ kubectl apply -f awx-secret-tls.yaml
 - [📁 **Use Customized Pod Specification for your Execution Environment**](containergroup)
   - The guide to use customized Pod of the Execution Environment using **Container Group**.
 - [📁 **Tips**](tips)
+  - [📝Deploy AWX using external PostgreSQL database](tips/external-db.md)
   - [📝Expose `/etc/hosts` to Pods on K3s](tips/expose-hosts.md)
   - [📝Redirect HTTP to HTTPS](tips/https-redirection.md)
   - [📝Uninstall deployed resouces](tips/uninstall.md)
diff --git a/tips/README.md b/tips/README.md
index 1ace3e6..893b2cc 100644
--- a/tips/README.md
+++ b/tips/README.md
@@ -1,5 +1,6 @@
 # Tips
 
+- [📝Deploy AWX using external PostgreSQL database](external-db.md)
 - [📝Expose `/etc/hosts` to Pods on K3s](expose-hosts.md)
 - [📝Redirect HTTP to HTTPS](https-redirection.md)
 - [📝Uninstall deployed resouces](uninstall.md)
diff --git a/tips/external-db.md b/tips/external-db.md
new file mode 100644
index 0000000..f4805c3
--- /dev/null
+++ b/tips/external-db.md
@@ -0,0 +1,122 @@
+<!-- omit in toc -->
+# Deploy AWX using external PostgreSQL database
+
+The guide to deploy AWX using your existing external PostgreSQL database. The overview of the procedure is almost the same as [the main guide](../), but a few additional files need to be modified.
+
+<!-- omit in toc -->
+## Table of Contents
+
+- [Prepare PostgreSQL](#prepare-postgresql)
+- [Prepare required files](#prepare-required-files)
+  - [Modify `base/awx.yaml`](#modify-baseawxyaml)
+  - [Modify `base/kustomization.yaml`](#modify-basekustomizationyaml)
+  - [Modify `base/pv.yaml`](#modify-basepvyaml)
+  - [Prepare directories](#prepare-directories)
+- [The next steps](#the-next-steps)
+
+## Prepare PostgreSQL
+
+Prepare your PostgreSQL.
+
+Here, for the simplest example, I prepared it on another host (named `postgres.example.internal`) using Docker Compose.
+
+```yaml
+version: "3"
+
+services:
+  postgres:
+    image: postgres:12
+    ports:
+      - 5432:5432
+    restart: always
+    environment:
+      - POSTGRES_DB=awx
+      - POSTGRES_USER=awx
+      - POSTGRES_PASSWORD=SecurePasswordForMyExternalPostgreSQLForAWX123!
+    volumes:
+      - "postgres-data:/var/lib/postgresql/data"
+
+volumes:
+  postgres-data:
+```
+
+## Prepare required files
+
+In addition to the steps in [the main guide (`README.md`)](../), here are a few additional files that need to be modified before you deploy AWX.
+
+### Modify `base/awx.yaml`
+
+Comment out following four lines which are unnecessary settings in `base/awx.yaml`.
+
+```yaml
+...
+spec:
+  ...
+  postgres_configuration_secret: awx-postgres-configuration
+
+  # postgres_storage_class: awx-postgres-volume     👈👈👈
+  # postgres_storage_requirements:     👈👈👈
+  #   requests:     👈👈👈
+  #     storage: 2Gi     👈👈👈
+
+  projects_persistence: true
+  projects_existing_claim: awx-projects-claim
+  ...
+```
+
+### Modify `base/kustomization.yaml`
+
+Replace and modify following lines under `awx-postgres-configuration` in `base/kustomization.yaml` to suit your environment.
+
+```yaml
+secretGenerator:
+  ...
+  - name: awx-postgres-configuration
+    type: Opaque
+    literals:
+      - host=postgres.example.internal     👈👈👈
+      - port=5432     👈👈👈
+      - database=awx     👈👈👈
+      - username=awx     👈👈👈
+      - password=SecurePasswordForMyExternalPostgreSQLForAWX123!     👈👈👈
+      - sslmode=prefer     👈👈👈
+      - type=unmanaged     👈👈👈
+```
+
+Note that the `type=unmanaged` is the important configuration to use external database.
+
+### Modify `base/pv.yaml`
+
+Comment out following unnecessary lines which related to `awx-postgres-volume` in `base/pv.yaml`.
+
+```yaml
+# ---     👈👈👈
+# apiVersion: v1     👈👈👈
+# kind: PersistentVolume     👈👈👈
+# metadata:     👈👈👈
+#   name: awx-postgres-volume     👈👈👈
+# spec:     👈👈👈
+#   accessModes:     👈👈👈
+#     - ReadWriteOnce     👈👈👈
+#   persistentVolumeReclaimPolicy: Retain     👈👈👈
+#   capacity:     👈👈👈
+#     storage: 2Gi     👈👈👈
+#   storageClassName: awx-postgres-volume     👈👈👈
+#   hostPath:     👈👈👈
+#     path: /data/postgres     👈👈👈
+
+---
+apiVersion: v1
+kind: PersistentVolume
+metadata:
+  name: awx-projects-volume
+...
+```
+
+### Prepare directories
+
+You do not need to create the `/data/postgres` directory that the main guide instructs you to create.
+
+## The next steps
+
+The other steps are the same as in [the main guide (`README.md`)](../). Have fun!