This is an automated email from the ASF dual-hosted git repository.
jbonofre 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 fcb6b3397 Fix Issue 2024 for Rendering Blockquotes (#2656)
fcb6b3397 is described below
commit fcb6b33978aa4557b0da0251fab8a7d39ae14def
Author: Adam Christian
<[email protected]>
AuthorDate: Wed Sep 24 00:42:40 2025 -0400
Fix Issue 2024 for Rendering Blockquotes (#2656)
* Fix Issue 2024 for Rendering Blockquotes
* Small fix for URLs
* Update license
---
site/content/in-dev/unreleased/_index.md | 44 +++++++------
site/content/in-dev/unreleased/admin-tool.md | 9 +--
site/content/in-dev/unreleased/configuration.md | 24 ++++---
.../configuring-polaris-for-production.md | 23 ++++---
site/content/in-dev/unreleased/helm.md | 14 ++--
.../managing-security/external-idp/_index.md | 4 +-
site/content/in-dev/unreleased/metastores.md | 23 +++----
site/content/in-dev/unreleased/policy.md | 7 +-
site/layouts/_markup/render-blockquote.html | 53 ---------------
site/layouts/shortcodes/alert.html | 75 ++++++++++++++++++++++
10 files changed, 158 insertions(+), 118 deletions(-)
diff --git a/site/content/in-dev/unreleased/_index.md
b/site/content/in-dev/unreleased/_index.md
index 183641f70..dbe906cec 100644
--- a/site/content/in-dev/unreleased/_index.md
+++ b/site/content/in-dev/unreleased/_index.md
@@ -31,10 +31,11 @@ cascade:
# This file will NOT be copied into a new release's versioned docs folder.
---
-> [!WARNING]
-> These pages refer to the current state of the main branch, which is still
under active development.
->
-> Functionalities can be changed, removed or added without prior notice.
+{{< alert warning >}}
+These pages refer to the current state of the main branch, which is still
under active development.
+
+Functionalities can be changed, removed or added without prior notice.
+{{< /alert >}}
Apache Polaris (Incubating) is a catalog implementation for Apache
Iceberg™ tables and is built on the open source Apache Iceberg™
REST protocol.
@@ -82,23 +83,24 @@ A catalog is configured with a storage configuration that
can point to S3, Azure
You create *namespaces* to logically group Iceberg tables within a catalog. A
catalog can have multiple namespaces. You can also create
nested namespaces. Iceberg tables belong to namespaces.
-> [!Important]
-> For the access privileges defined for a catalog to be enforced correctly,
the following conditions must be met:
->
-> - The directory only contains the data files that belong to a single table.
-> - The directory hierarchy matches the namespace hierarchy for the catalog.
->
-> For example, if a catalog includes the following items:
->
-> - Top-level namespace namespace1
-> - Nested namespace namespace1a
-> - A customers table, which is grouped under nested namespace namespace1a
-> - An orders table, which is grouped under nested namespace namespace1a
->
-> The directory hierarchy for the catalog must follow this structure:
->
-> - /namespace1/namespace1a/customers/<files for the customers table *only*>
-> - /namespace1/namespace1a/orders/<files for the orders table *only*>
+{{< alert important >}}
+For the access privileges defined for a catalog to be enforced correctly, the
following conditions must be met:
+
+- The directory only contains the data files that belong to a single table.
+- The directory hierarchy matches the namespace hierarchy for the catalog.
+
+For example, if a catalog includes the following items:
+
+- Top-level namespace namespace1
+- Nested namespace namespace1a
+- A customers table, which is grouped under nested namespace namespace1a
+- An orders table, which is grouped under nested namespace namespace1a
+
+The directory hierarchy for the catalog must follow this structure:
+
+- /namespace1/namespace1a/customers/<files for the customers table *only*>
+- /namespace1/namespace1a/orders/<files for the orders table *only*>
+{{< /alert >}}
### Storage configuration
diff --git a/site/content/in-dev/unreleased/admin-tool.md
b/site/content/in-dev/unreleased/admin-tool.md
index 4caa9d534..accfdcd52 100644
--- a/site/content/in-dev/unreleased/admin-tool.md
+++ b/site/content/in-dev/unreleased/admin-tool.md
@@ -116,10 +116,11 @@ java -jar runtime/admin/build/quarkus-app/quarkus-run.jar
bootstrap -r realm1 -c
The `purge` command is used to remove realms and principal credentials from
the Polaris server.
-> [!WARNING]
-> Running the `purge` command will remove all data associated with the
specified realms!
- This includes all entities (catalogs, namespaces, tables, views, roles), all
principal
- credentials, grants, and any other data associated with the realms.
+{{< alert warning >}}
+Running the `purge` command will remove all data associated with the specified
realms!
+This includes all entities (catalogs, namespaces, tables, views, roles), all
principal
+credentials, grants, and any other data associated with the realms.
+{{< /alert >}}
```shell
java -jar runtime/admin/build/quarkus-app/quarkus-run.jar purge --help
diff --git a/site/content/in-dev/unreleased/configuration.md
b/site/content/in-dev/unreleased/configuration.md
index 103b8c948..61ea79378 100644
--- a/site/content/in-dev/unreleased/configuration.md
+++ b/site/content/in-dev/unreleased/configuration.md
@@ -28,8 +28,9 @@ This page provides information on how to configure Apache
Polaris (Incubating).
otherwise, this information is valid both for Polaris Docker images (and
Kubernetes deployments) as
well as for Polaris binary distributions.
-> [!NOTE]
-> For Production tips and best practices, refer to [Configuring Polaris for
Production]({{% ref "configuring-polaris-for-production.md" %}}).
+{{< alert note >}}
+For Production tips and best practices, refer to [Configuring Polaris for
Production]({{% ref "configuring-polaris-for-production.md" %}}).
+{{< /alert >}}
First off, Polaris server runs on Quarkus, and uses its configuration
mechanisms. Read Quarkus
[configuration guide](https://quarkus.io/guides/config) to get familiar with
the basics.
@@ -64,9 +65,11 @@ When using environment variables, there are two naming
conventions:
`polaris.realm-context.realms` becomes `POLARIS_REALM_CONTEXT_REALMS`. See
[here](https://smallrye.io/smallrye-config/Main/config/environment-variables/)
for more details.
-> [!IMPORTANT]
-> While convenient, uppercase-only environment variables can be problematic
for complex property
-> names. In these situations, it's preferable to use system properties or a
configuration file.
+{{< alert important >}}
+While convenient, uppercase-only environment variables can be problematic for
complex property
+names. In these situations, it's preferable to use system properties or a
configuration file.
+{{< /alert >}}
+
As stated above, a configuration file can also be provided at runtime; it
should be available
(mounted) at `$PWD/config/application.properties` for Polaris server to
recognize it. In Polaris
@@ -145,8 +148,9 @@ There are non Polaris configuration properties that can be
useful:
| `quarkus.management.root-path` |
| Define the root path where `/metrics` and `/health` endpoints are
based on. |
| `quarkus.otel.sdk.disabled` | `true`
| Enable the OpenTelemetry layer.
|
-> [!NOTE]
-> This section is only relevant for Polaris Docker images and Kubernetes
deployments.
+{{< alert note >}}
+This section is only relevant for Polaris Docker images and Kubernetes
deployments.
+{{< /alert >}}
There are many other actionable environment variables available in the
official Polaris Docker
image; they come from the base image used by Polaris,
[ubi9/openjdk-21-runtime]. They should be used
@@ -191,5 +195,7 @@ quarkus.log.console.level=DEBUG
quarkus.log.category."io.smallrye.config".level=DEBUG
```
-> [!IMPORTANT] This will print out all configuration values, including
sensitive ones like
-> passwords. Don't do this in production, and don't share this output with
anyone you don't trust!
+{{< alert important >}}
+This will print out all configuration values, including sensitive ones like
+passwords. Don't do this in production, and don't share this output with
anyone you don't trust!
+{{< /alert >}}
diff --git
a/site/content/in-dev/unreleased/configuring-polaris-for-production.md
b/site/content/in-dev/unreleased/configuring-polaris-for-production.md
index befe4bba8..928d8115f 100644
--- a/site/content/in-dev/unreleased/configuring-polaris-for-production.md
+++ b/site/content/in-dev/unreleased/configuring-polaris-for-production.md
@@ -44,10 +44,11 @@ supported out of the box:
By default, Polaris uses `rsa-key-pair`, with randomly generated keys.
-> [!IMPORTANT]
-> The default `rsa-key-pair` configuration is not suitable when deploying many
replicas of Polaris,
-> as each replica will have its own set of keys. This will cause token
validation to fail when a
-> request is routed to a different replica than the one that issued the token.
+{{< alert important >}}
+The default `rsa-key-pair` configuration is not suitable when deploying many
replicas of Polaris,
+as each replica will have its own set of keys. This will cause token
validation to fail when a
+request is routed to a different replica than the one that issued the token.
+{{< /alert >}}
It is highly recommended to configure Polaris with previously-generated RSA
keys. This can be done
by setting the following properties:
@@ -129,9 +130,10 @@ in the request.
A metastore should be configured with an implementation that durably persists
Polaris entities. By
default, Polaris uses an in-memory metastore.
-> [!IMPORTANT]
-> The default in-memory metastore is not suitable for production use, as it
will lose all data
-> when the server is restarted; it is also unusable when multiple Polaris
replicas are used.
+{{< alert important >}}
+The default in-memory metastore is not suitable for production use, as it will
lose all data
+when the server is restarted; it is also unusable when multiple Polaris
replicas are used.
+{{< /alert >}}
To enable a durable metastore, configure your system to use the Relational
JDBC-backed metastore.
This implementation leverages Quarkus for datasource management and supports
configuration through
@@ -152,9 +154,10 @@ The relational JDBC metastore is a Quarkus-managed
datasource and only supports
Please refer to the documentation here:
[Configure data sources in Quarkus](https://quarkus.io/guides/datasource)
-> [!IMPORTANT]
-> Be sure to secure your metastore backend since it will be storing sensitive
data and catalog
-> metadata.
+{{< alert important >}}
+Be sure to secure your metastore backend since it will be storing sensitive
data and catalog
+metadata.
+{{< /alert >}}
Note: Polaris will always create schema 'polaris_schema' during bootstrap
under the configured database.
diff --git a/site/content/in-dev/unreleased/helm.md
b/site/content/in-dev/unreleased/helm.md
index ed4545cac..ef82e8e67 100644
--- a/site/content/in-dev/unreleased/helm.md
+++ b/site/content/in-dev/unreleased/helm.md
@@ -79,10 +79,11 @@ fail if these resources are not created beforehand. You can
find some examples i
Below are two sample deployment models for installing the chart: one with a
non-persistent backend and another with a persistent backend.
-> [!WARNING]
-> The examples below use values files located in the `helm/polaris/ci`
directory.
-> **These files are intended for testing purposes primarily, and may not be
suitable for production use**.
-> For production deployments, create your own values files based on the
provided examples.
+{{< alert warning >}}
+The examples below use values files located in the `helm/polaris/ci` directory.
+**These files are intended for testing purposes primarily, and may not be
suitable for production use**.
+For production deployments, create your own values files based on the provided
examples.
+{{< /alert >}}
#### Non-persistent backend
@@ -94,8 +95,9 @@ helm upgrade --install --namespace polaris \
#### Persistent backend
-> [!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.
+{{< alert 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.
+{{< /alert >}}
Install the chart with a persistent backend. From Polaris repo root:
```bash
diff --git
a/site/content/in-dev/unreleased/managing-security/external-idp/_index.md
b/site/content/in-dev/unreleased/managing-security/external-idp/_index.md
index ff286b9f0..6767924c5 100644
--- a/site/content/in-dev/unreleased/managing-security/external-idp/_index.md
+++ b/site/content/in-dev/unreleased/managing-security/external-idp/_index.md
@@ -157,7 +157,9 @@
polaris.oidc.oidc-tenant1.principal-mapper.id-claim-path=polaris/principal_id
polaris.oidc.oidc-tenant1.principal-mapper.name-claim-path=polaris/principal_name
```
-> [!IMPORTANT]: The default implementation of PrincipalMapper can only work
with JWT tokens. If your IDP issues opaque tokens instead, you will need to
provide a custom implementation.
+{{< alert important >}}
+The default implementation of PrincipalMapper can only work with JWT tokens.
If your IDP issues opaque tokens instead, you will need to provide a custom
implementation.
+{{< /alert >}}
### Role Mapping
diff --git a/site/content/in-dev/unreleased/metastores.md
b/site/content/in-dev/unreleased/metastores.md
index 3c4ec9979..ef5a5ae94 100644
--- a/site/content/in-dev/unreleased/metastores.md
+++ b/site/content/in-dev/unreleased/metastores.md
@@ -45,11 +45,9 @@ Please refer to the documentation here:
Additionally, the retries can be configured via
`polaris.persistence.relational.jdbc.*` properties please ref
[configuration]({{% ref "configuration" %}})
## EclipseLink (Deprecated)
-> [!IMPORTANT]
-> EclipseLink is deprecated, it is recommended to use Relational JDBC as
persistence instead.
-
-> [!IMPORTANT]
-> EclipseLink persistence will be completely removed from Polaris in 1.3.0 or
in 2.0.0 (whichever happens earlier).
+{{< alert important >}}
+EclipseLink persistence will be completely removed from Polaris in 1.3.0 or in
2.0.0 (whichever happens earlier).
+{{< /alert >}}
Polaris includes EclipseLink plugin by default with PostgresSQL driver.
@@ -69,22 +67,25 @@ The `configuration-file` option must point to an
[EclipseLink configuration file
`persistence.xml`, is used to set up the database connection properties, which
can differ depending
on the type of database and its configuration.
-> [!NOTE]
-> You have to locate the `persistence.xml` at least two folders down to the
root folder, e.g. `/deployments/config/persistence.xml` is OK, whereas
`/deployments/persistence.xml` will cause an infinity loop.
+{{< alert note >}}
+You have to locate the `persistence.xml` at least two folders down to the root
folder, e.g. `/deployments/config/persistence.xml` is OK, whereas
`/deployments/persistence.xml` will cause an infinity loop.
+{{< /alert >}}
[Quarkus Configuration Reference]: https://quarkus.io/guides/config-reference
[EclipseLink configuration file]:
https://eclipse.dev/eclipselink/documentation/4.0/solutions/solutions.html#TESTINGJPA002
Polaris creates and connects to a separate database for each realm.
Specifically, the `{realm}` placeholder in `jakarta.persistence.jdbc.url` is
substituted with the actual realm name, allowing the Polaris server to connect
to different databases based on the realm.
-> [!NOTE]
-> Some database systems such as Postgres don't create databases automatically.
Database admins need to create them manually before running Polaris server.
+{{< alert note >}}
+Some database systems such as Postgres don't create databases automatically.
Database admins need to create them manually before running Polaris server.
+{{< /alert >}}
A single `persistence.xml` can describe multiple [persistence
units](https://eclipse.dev/eclipselink/documentation/4.0/concepts/concepts.html#APPDEV001).
For example, with both a `polaris-dev` and `polaris` persistence unit defined,
you could use a single `persistence.xml` to easily switch between development
and production databases. Use the `persistence-unit` option in the Polaris
server configuration to easily switch between persistence units.
### Using H2
-> [!IMPORTANT]
-> H2 is an in-memory database and is not suitable for production!
+{{< alert important >}}
+H2 is an in-memory database and is not suitable for production!
+{{< /alert >}}
The default [persistence.xml] in Polaris is already configured for H2, but you
can easily customize
your H2 configuration using the persistence unit template below:
diff --git a/site/content/in-dev/unreleased/policy.md
b/site/content/in-dev/unreleased/policy.md
index e96661f3f..5ad26edd4 100644
--- a/site/content/in-dev/unreleased/policy.md
+++ b/site/content/in-dev/unreleased/policy.md
@@ -81,9 +81,10 @@ The inheritance follows an override mechanism:
1. Table-level policies override namespace and catalog policies
2. Namespace-level policies override parent namespace and catalog policies
-> [!IMPORTANT]
-> Because an override completely replaces the same policy type at higher
levels,
-> **only one instance of a given policy type can be attached to (and therefore
affect) a resource**.
+{{< alert important >}}
+Because an override completely replaces the same policy type at higher levels,
+**only one instance of a given policy type can be attached to (and therefore
affect) a resource**.
+{{< /alert >}}
## Working with Policies
diff --git a/site/layouts/_markup/render-blockquote.html
b/site/layouts/_markup/render-blockquote.html
deleted file mode 100644
index 1430f356e..000000000
--- a/site/layouts/_markup/render-blockquote.html
+++ /dev/null
@@ -1,53 +0,0 @@
-{{/*
-Licensed to the Apache Software Foundation (ASF) under one
-or more contributor license agreements. See the NOTICE file
-distributed with this work for additional information
-regarding copyright ownership. The ASF licenses this file
-to you under the Apache License, Version 2.0 (the
-"License"); you may not use this file except in compliance
-with the License. You may obtain a copy of the License at
-
-http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing,
-software distributed under the License is distributed on an
-"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-KIND, either express or implied. See the License for the
-specific language governing permissions and limitations
-under the License.
-*/}}
-
-{{- /* Define emojis and handle the case where .AlertType is not found */ -}}
-{{- $emojis := dict
- "danger" ":stop_sign:"
- "error" ":x:"
- "caution" ":warning:"
- "warning" ":warning:"
- "important" ":exclamation:"
- "info" ":information_source:"
- "note" ":memo:"
- "tip" ":bulb:"
- "success" ":white_check_mark:"
- "primary" ":information_source:"
--}}
-
-{{- if eq .Type "alert" -}}
- <blockquote class="alert alert-{{ .AlertType }}">
- {{- /* Check for emoji, with a sensible default */ -}}
- {{- $emoji := index $emojis .AlertType | default ":information_source:" -}}
- <p class="alert-heading">
- {{- transform.Emojify $emoji -}}
- {{- /* Check for custom title, otherwise use i18n or title case */ -}}
- {{- with .AlertTitle -}}
- {{- . -}}
- {{- else -}}
- {{- or (i18n .AlertType) (title .AlertType) -}}
- {{- end -}}
- </p>
- {{- .Text | safeHTML -}}
- </blockquote>
-{{- else -}}
- <blockquote>
- {{- .Text | safeHTML -}}
- </blockquote>
-{{- end -}}
diff --git a/site/layouts/shortcodes/alert.html
b/site/layouts/shortcodes/alert.html
new file mode 100644
index 000000000..d72ab09ab
--- /dev/null
+++ b/site/layouts/shortcodes/alert.html
@@ -0,0 +1,75 @@
+{{/*
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+*/}}
+{{- $type := .Get 0 | default "info" | lower -}}
+{{- $title := .Get 1 | default "" -}}
+
+{{- /* Define emoji mappings for different alert types */ -}}
+{{- $emojis := dict
+ "danger" "đ "
+ "error" "â "
+ "caution" "â ī¸ "
+ "warning" "â ī¸ "
+ "important" "â"
+ "info" "âšī¸ "
+ "note" "đ "
+ "tip" "đĄ "
+ "success" "â
"
+ "primary" "âšī¸ "
+-}}
+
+{{- /* Define title mappings for different alert types */ -}}
+{{- $titles := dict
+ "danger" "Danger"
+ "error" "Error"
+ "caution" "Caution"
+ "warning" "Warning"
+ "important" "Important"
+ "info" "Info"
+ "note" "Note"
+ "tip" "Tip"
+ "success" "Success"
+ "primary" "Info"
+-}}
+
+{{- /* Define styles for different alert types */ -}}
+{{- $styles := dict
+"danger" "danger"
+"error" "danger"
+"caution" "danger"
+"warning" "warning"
+"important" "primary"
+"info" "info"
+"note" "info"
+"tip" "info"
+"success" "success"
+"primary" "primary"
+-}}
+
+<div class="alert alert-{{- index $styles $type -}}">
+ {{- $emoji := index $emojis $type | default "âšī¸" -}}
+ <p class="alert-heading">
+ {{ $emoji }}
+ {{- if $title -}}
+ {{ $title }}
+ {{- else -}}
+ {{ index $titles $type | default (title $type) }}
+ {{- end -}}
+ </p>
+ {{ .Inner | .Page.RenderString }}
+</div>
