This is an automated email from the ASF dual-hosted git repository.
yufei pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/polaris.git
The following commit(s) were added to refs/heads/main by this push:
new a95026c4a Doc: catalog bootstrap steps for helm deployment (#1243)
a95026c4a is described below
commit a95026c4ac11ba3a132b9a2268b84bf6af1eff8f
Author: MonkeyCanCode <yongzheng0...@gmail.com>
AuthorDate: Tue Mar 25 00:08:31 2025 -0500
Doc: catalog bootstrap steps for helm deployment (#1243)
---
helm/polaris/README.md | 69 +++++++++++++++++++++++++++++----
helm/polaris/README.md.gotmpl | 71 ++++++++++++++++++++++++++++++----
helm/polaris/ci/fixtures/postgres.yaml | 12 +++---
3 files changed, 131 insertions(+), 21 deletions(-)
diff --git a/helm/polaris/README.md b/helm/polaris/README.md
index 312571d78..586a99107 100644
--- a/helm/polaris/README.md
+++ b/helm/polaris/README.md
@@ -96,14 +96,32 @@ eval $(minikube -p minikube docker-env)
The below instructions assume a local Kubernetes cluster is running and Helm
is installed.
+#### Common setup
+
Create and populate the target namespace:
```bash
kubectl create namespace polaris
kubectl apply --namespace polaris -f helm/polaris/ci/fixtures/
+
+kubectl wait --namespace polaris --for=condition=ready pod
--selector=app.kubernetes.io/name=postgres --timeout=120s
+```
+
+The `helm/polaris/ci` contains a number of values files that can be used to
install the chart with
+different configurations.
+
+You can also run `ct` (chart-testing):
+
+```bash
+ct lint --charts helm/polaris
+ct install --namespace polaris --debug --charts ./helm/polaris
```
-Finally, install the chart. From Polaris repo root:
+Below are two sample deployment models for installing the chart: one with a
non-persistent backend and another with a persistent backend.
+
+#### Non-persistent backend
+
+Install the chart with a non-persistent backend. From Polaris repo root:
```bash
helm upgrade --install --namespace polaris \
@@ -111,20 +129,57 @@ helm upgrade --install --namespace polaris \
polaris helm/polaris
```
-The `helm/polaris/ci` contains a number of values files that can be used to
install the chart with
-different configurations.
+#### Persistent backend
-You can also run `ct` (chart-testing):
+> [!WARNING]
+> The Postgres deployment set up in the fixtures directory is intended for
testing purposes only and is not suitable for production use. For production
deployments, use a managed Postgres service or a properly configured and
secured Postgres instance.
+
+Install the chart with a persistent backend. From Polaris repo root:
```bash
-ct lint --charts helm/polaris
-ct install --namespace polaris --debug --charts ./helm/polaris
+helm upgrade --install --namespace polaris \
+ --debug --values helm/polaris/ci/persistence-values.yaml \
+ polaris helm/polaris
+
+kubectl wait --namespace polaris --for=condition=ready pod
--selector=app.kubernetes.io/name=polaris --timeout=120s
+```
+
+After deploying the chart with a persistent backend, the `persistence.xml`
file, originally loaded into the Kubernetes pod via a secret, can be accessed
locally if needed. This file contains the persistence configuration required
for the next steps. Use the following command to retrieve it:
+
+```bash
+kubectl exec -it -n polaris $(kubectl get pod -n polaris -l
app.kubernetes.io/name=polaris -o jsonpath='{.items[0].metadata.name}') -- cat
/deployments/config/persistence.xml > persistence.xml
+```
+
+The `persistence.xml` file references the Postgres hostname as postgres.
Update it to localhost to enable local connections:
+
+```bash
+sed -i .bak 's/postgres:/localhost:/g' persistence.xml
```
-### Uninstalling the chart
+To access Polaris and Postgres locally, set up port forwarding for both
services:
+```bash
+kubectl port-forward -n polaris $(kubectl get pod -n polaris -l
app.kubernetes.io/name=polaris -o jsonpath='{.items[0].metadata.name}')
8181:8181
+
+kubectl port-forward -n polaris $(kubectl get pod -n polaris -l
app.kubernetes.io/name=postgres -o jsonpath='{.items[0].metadata.name}')
5432:5432
+```
+
+Run the catalog bootstrap using the Polaris admin tool. This step initializes
the catalog with the required configuration:
+
+```bash
+java -Dpolaris.persistence.eclipselink.configuration-file=./persistence.xml \
+ -Dpolaris.persistence.eclipselink.persistence-unit=polaris \
+ -jar quarkus/admin/build/polaris-quarkus-admin-*-runner.jar \
+ bootstrap -c POLARIS,root,pass -r POLARIS
+```
+
+### Uninstalling
```bash
helm uninstall --namespace polaris polaris
+
+kubectl delete --namespace polaris -f helm/polaris/ci/fixtures/
+
+kubectl delete namespace polaris
```
## Values
diff --git a/helm/polaris/README.md.gotmpl b/helm/polaris/README.md.gotmpl
index d443c62f8..a41a3cfc2 100644
--- a/helm/polaris/README.md.gotmpl
+++ b/helm/polaris/README.md.gotmpl
@@ -97,14 +97,32 @@ eval $(minikube -p minikube docker-env)
The below instructions assume a local Kubernetes cluster is running and Helm
is installed.
+#### Common setup
+
Create and populate the target namespace:
```bash
kubectl create namespace polaris
kubectl apply --namespace polaris -f helm/polaris/ci/fixtures/
+
+kubectl wait --namespace polaris --for=condition=ready pod
--selector=app.kubernetes.io/name=postgres --timeout=120s
+```
+
+The `helm/polaris/ci` contains a number of values files that can be used to
install the chart with
+different configurations.
+
+You can also run `ct` (chart-testing):
+
+```bash
+ct lint --charts helm/polaris
+ct install --namespace polaris --debug --charts ./helm/polaris
```
-Finally, install the chart. From Polaris repo root:
+Below are two sample deployment models for installing the chart: one with a
non-persistent backend and another with a persistent backend.
+
+#### Non-persistent backend
+
+Install the chart with a non-persistent backend. From Polaris repo root:
```bash
helm upgrade --install --namespace polaris \
@@ -112,20 +130,57 @@ helm upgrade --install --namespace polaris \
polaris helm/polaris
```
-The `helm/polaris/ci` contains a number of values files that can be used to
install the chart with
-different configurations.
+#### Persistent backend
-You can also run `ct` (chart-testing):
+> [!WARNING]
+> The Postgres deployment set up in the fixtures directory is intended for
testing purposes only and is not suitable for production use. For production
deployments, use a managed Postgres service or a properly configured and
secured Postgres instance.
+
+Install the chart with a persistent backend. From Polaris repo root:
```bash
-ct lint --charts helm/polaris
-ct install --namespace polaris --debug --charts ./helm/polaris
+helm upgrade --install --namespace polaris \
+ --debug --values helm/polaris/ci/persistence-values.yaml \
+ polaris helm/polaris
+
+kubectl wait --namespace polaris --for=condition=ready pod
--selector=app.kubernetes.io/name=polaris --timeout=120s
+```
+
+After deploying the chart with a persistent backend, the `persistence.xml`
file, originally loaded into the Kubernetes pod via a secret, can be accessed
locally if needed. This file contains the persistence configuration required
for the next steps. Use the following command to retrieve it:
+
+```bash
+kubectl exec -it -n polaris $(kubectl get pod -n polaris -l
app.kubernetes.io/name=polaris -o jsonpath='{.items[0].metadata.name}') -- cat
/deployments/config/persistence.xml > persistence.xml
+```
+
+The `persistence.xml` file references the Postgres hostname as postgres.
Update it to localhost to enable local connections:
+
+```bash
+sed -i .bak 's/postgres:/localhost:/g' persistence.xml
```
-### Uninstalling the chart
+To access Polaris and Postgres locally, set up port forwarding for both
services:
+```bash
+kubectl port-forward -n polaris $(kubectl get pod -n polaris -l
app.kubernetes.io/name=polaris -o jsonpath='{.items[0].metadata.name}')
8181:8181
+
+kubectl port-forward -n polaris $(kubectl get pod -n polaris -l
app.kubernetes.io/name=postgres -o jsonpath='{.items[0].metadata.name}')
5432:5432
+```
+
+Run the catalog bootstrap using the Polaris admin tool. This step initializes
the catalog with the required configuration:
+
+```bash
+java -Dpolaris.persistence.eclipselink.configuration-file=./persistence.xml \
+ -Dpolaris.persistence.eclipselink.persistence-unit=polaris \
+ -jar quarkus/admin/build/polaris-quarkus-admin-*-runner.jar \
+ bootstrap -c POLARIS,root,pass -r POLARIS
+```
+
+### Uninstalling
```bash
helm uninstall --namespace polaris polaris
+
+kubectl delete --namespace polaris -f helm/polaris/ci/fixtures/
+
+kubectl delete namespace polaris
```
-{{ template "chart.valuesSection" . }}
\ No newline at end of file
+{{ template "chart.valuesSection" . }}
diff --git a/helm/polaris/ci/fixtures/postgres.yaml
b/helm/polaris/ci/fixtures/postgres.yaml
index 155321d96..ac3179d23 100644
--- a/helm/polaris/ci/fixtures/postgres.yaml
+++ b/helm/polaris/ci/fixtures/postgres.yaml
@@ -25,11 +25,11 @@ spec:
replicas: 1
selector:
matchLabels:
- app: postgres
+ app.kubernetes.io/name: postgres
template:
metadata:
labels:
- app: postgres
+ app.kubernetes.io/name: postgres
spec:
containers:
- name: postgres
@@ -65,8 +65,8 @@ metadata:
name: postgres
spec:
selector:
- app: postgres
+ app.kubernetes.io/name: postgres
ports:
- - protocol: TCP
- port: 5432
- targetPort: 5432
+ - protocol: TCP
+ port: 5432
+ targetPort: 5432
