diff --git a/.github/workflows/check-md-link.yml b/.github/workflows/check-md-link.yml index c71dc5fd8..0cf76693c 100644 --- a/.github/workflows/check-md-link.yml +++ b/.github/workflows/check-md-link.yml @@ -46,5 +46,6 @@ jobs: - uses: gaurav-nelson/github-action-markdown-link-check@v1 with: config-file: '.github/workflows/check-md-link-config.json' - folder-path: '., docs, regtests, regtests/client/python/docs, regtests/client/python' + folder-path: 'regtests, regtests/client/python/docs, regtests/client/python, .github, build-logic, polaris-core, polaris-service, extension, spec, k8, notebooks' + file-path: 'CHAT_BYLAWS.md, CODE_OF_CONDUCT.md, CONTRIBUTING.md, README.md SECURITY.md' use-quiet-mode: true diff --git a/.gitignore b/.gitignore index f9b35731c..c49fc7816 100644 --- a/.gitignore +++ b/.gitignore @@ -64,6 +64,9 @@ gradle/wrapper/gradle-wrapper-*.sha256 **/build/ !src/**/build/ +# npm +node_modules/ + # jenv .java-version diff --git a/build.gradle.kts b/build.gradle.kts index 12828e156..1d69ac3ff 100644 --- a/build.gradle.kts +++ b/build.gradle.kts @@ -86,6 +86,11 @@ tasks.named("rat").configure { excludes.add("polaris-service/src/**/banner.txt") excludes.add("polaris-service/logs") + excludes.add("site/node_modules/**") + excludes.add("site/public/**") + excludes.add("site/resources/_gen/**") + excludes.add("site/layouts/robots.txt") + excludes.add("**/polaris-venv/**") excludes.add("**/.pytest_cache/**") @@ -108,6 +113,8 @@ tasks.named("rat").configure { excludes.add("**/*.lock") excludes.add("**/*.env*") + + excludes.add("**/go.sum") } // Pass environment variables: diff --git a/docker-compose-hugo.yml b/docker-compose-hugo.yml new file mode 100644 index 000000000..2c4c555f5 --- /dev/null +++ b/docker-compose-hugo.yml @@ -0,0 +1,52 @@ +# +# 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. +# + +services: + hugo: + build: + context: site/docker + ports: + - "1313:1313" + healthcheck: + test: ["CMD", "curl", "http://localhost:1313/"] + interval: 10s + timeout: 10s + retries: 5 + volumes: + - workspace:/polaris + - resource_gen:/polaris/site/resources/_gen + - hugo_cache:/hugo/cache + +volumes: + workspace: + # This is the polaris source tree + driver: local + driver_opts: + # set UID+GID so podman doesn't "chown" the Polaris workspace to an ephemeral UID (Linux only) + o: $BIND_ARG + type: none + device: . + hugo_cache: + # 'hugo_cache' is the Go modules cache - just keep it across restarts + resource_gen: + # tmpfs mount for the generated `resources/_gen` dir (no way to move that elsewhere :( ) + driver: local + driver_opts: + type: tmpfs + device: tmpfs diff --git a/site/.gitignore b/site/.gitignore new file mode 100644 index 000000000..7f738c57a --- /dev/null +++ b/site/.gitignore @@ -0,0 +1,23 @@ +# +# 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. +# + +.hugo_build.lock +content/releases/ +public/ +resources/_gen/ diff --git a/site/README.md b/site/README.md new file mode 100644 index 000000000..87f432911 --- /dev/null +++ b/site/README.md @@ -0,0 +1,169 @@ +Theme being used: https://www.docsy.dev/docs/ https://github.com/google/docsy/ + +Asciidoc help: https://docs.asciidoctor.org/asciidoc/latest/ + +Fontawesome logos/icons: https://fontawesome.com/v6/search?o=r&m=free + +# Quickstart + +Just run the following command to let Hugo serve files from the Polaris `site/`. +```bash +site/bin/run-hugo-in-docker.sh +``` + +Then point your browser to http://localhost:1313/ + +To stop the Hugo run +```bash +site/bin/stop-hugo-in-docker.sh +``` + +# Install Hugo + asciidoctor locally + +https://gohugo.io/installation/ + +## Ubuntu + +To develop the site locally (aka `hugo serve -D`), install the following dependencies using the `root` user: +```bash +apt install hugo asciidoctor +snap install dart-sass +``` + +If you want to build the static site locally as well (aka build with `hugo` + serve using another http server), +the following dependencies are needed as well (non-root user): +```bash +npm i -D postcss postcss-cli autoprefixer +npm install http-server -g +``` + +## macOS + +To develop the site locally (aka `hugo serve -D`), install the following dependencies: +```bash +brew install go +brew install hugo +brew install asciidoctor +``` + +If you want to build the static site locally as well (aka build with `hugo` + serve using another http server), +the following dependencies are needed as well (non-root user): +```bash +brew install npm +npm -i -D postcss postcss-cli autoprefixer +npm install http-server -g +``` + +# Versioned docs + +(See [`/releases/` page](content/releases/_index.adoc) as well.) + +The idea here is that docs of releases live in either a separate branch or a separate Git repo. + +The `/releases` folder would _not_ be in the main Polaris repository (at least not in any code branch). It would be +mounted either via `git worktree` or `git clone`. Building and testing the site locally works without the `/releases` +folder. For developers, it is probably much easier to have a separate branch in the main Polaris GitHub repository +and leverage Git worktrees. + +Docs for the current code branch (e.g. `main` branch) are maintained in the `/in-dev/unreleased` folder. While we +could maintain the docs right in the `/in-dev` folder, having the in-dev docs in `/in-dev/unreleased` provides the +ability to use relative links that still work when the docs are in an `/releases/x.y.z` folder (think: links like +`../../guides/foo-bar.md`). + +Within a release's versioned docs folder, the release version number can be included in the markdown using the +custom Hugo shortcode `{{< releaseVersion >}}`. + +## Git worktree + +The `content/releases/` folder is maintained in the separate `versioned-docs` branch. The whole `content/releases/` +folder is `.gitignore`d in the main source tree, otherwise Git complains about `content/releases` not being versioned +and if added to the main source tree (possible, Git allows that), the `git worktree add` below would complain about +the existing directory. + +### Initial setup + +```bash +cd site/ + +cd content/releases/ +# Create a new empty branch 'versioned-docs' +git worktree add --orphan -b versioned-docs . +# (add some content to the content/releases/ directory - at least the "top-level" _index.adoc +git add . +git commit -m "Initial set of releases" +``` + +### Locally + +Use the following script to checkout the versioned release docs +```bash +cd site/ +# Checkout the versioned-docs branch locally +bin/checkout-releases.sh +``` + +`bin/remove-releases.sh` removes the `content/releases` folder, if it does not contain uncommitted changes. + +## New release + +When a release is created, a bunch of things would happen via an automated GitHub workflow calling a shell script +in the main source tree: + +1. The releases versioned docs folder is created - for example: `/releases/0.1.0` +2. The contents of the `/in-dev/unreleased` folder are copied into the directory for the new release. + 1. The file `release_index.md` would be copied as `_index.md` into the new release's + versioned docs folder, the `/in-dev/unreleased/_index.md` would not end in the release's versioned docs folder. +3. The front-matter of the release's `_index.md` would be rewritten. +4. The new release is added to `params.active_releases` in `hugo.yaml` +5. When publishing a new release for the most recent major/minor version: + 1. The new release's `_index.md` would be generated with `exclude_search: false` + 2. The front-matter of the previous release's `_index.md` would be updated, + `exclude_search: false` changed to `exclude_search: true`. +6. When publishing a new release for an older major/minor version: + 1. The new release's `_index.md` would be generated with `exclude_search: true` +7. Changes to the site added and committed to Git +8. Changes pushed to GitHub - both the `main` and the `versioned-docs` folder +9. The last step triggers the job to publish the web site + +# Web site publishing (production) + +To build a site locally (not required for `hugo serve -D`, but required for `hugo`) - with your local user. + +This would be a GitHub workflow. + +1. Triggered when the `main` branch or the `versioned-docs` branch changes. +2. Checkout the `main` branch +3. ```bash + cd site/ + ``` +4. ```bash + git worktree add content/releases/ versioned-docs + ``` +5. ```bash + npm i -D postcss postcss-cli autoprefixer + ``` +6. ```bash + rm -rf public ; hugo --minify --gc + ``` +7. Publish the contents of the `public` folder to the website. + +## Test statically built web site locally + +The statically built web site in `public` _does not_ work when opened from the file system. + +Instead, do something like this: + +1. ```bash + rm -rf public ; hugo --minify --gc --baseURL http://localhost:8080/ + (cd public/ ; http-server -p 8080 --cors) + ``` +2. Then use your web browser to open http://localhost:8080/ + +# Noteworthy + +* The `redoc` shortcode works fine with `hugo serve` and on the static site configured via the `baseURL` in `hugo.yaml`. + To test the static build result locally, it is mandatory to pass the `--baseURL` option to `hugo`. +* The embedded `redoc` looks awful with a dark theme. +* The `swaggerui` shortcode doesn't seem to work? +* Some changes, especially those that change the site structure, requires a restart of `hugo serve -D`. This is also + true when the layout for the `robots.txt` is changed. diff --git a/site/assets/icons/logo.svg b/site/assets/icons/logo.svg new file mode 100644 index 000000000..5733be1f4 --- /dev/null +++ b/site/assets/icons/logo.svg @@ -0,0 +1,29 @@ + diff --git a/site/bin/checkout-releases.sh b/site/bin/checkout-releases.sh new file mode 100755 index 000000000..13bb1b318 --- /dev/null +++ b/site/bin/checkout-releases.sh @@ -0,0 +1,32 @@ +#!/usr/bin/env bash +# +# 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. +# + +set -e + +cd "$(dirname "$0")/.." + +git worktree prune + +if [[ -d content/releases ]] ; then + echo "Directory content/releases already exists" + exit 1 +fi + +git worktree add content/releases versioned-docs diff --git a/site/bin/remove-releases.sh b/site/bin/remove-releases.sh new file mode 100755 index 000000000..4a067d038 --- /dev/null +++ b/site/bin/remove-releases.sh @@ -0,0 +1,38 @@ +#!/usr/bin/env bash +# +# 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. +# + +set -e + +cd "$(dirname "$0")/.." + +if [[ ! -d content/releases ]] ; then + echo "Directory content/releases does not exists" + exit 1 +fi + +cd content/releases +if git diff-index --quiet HEAD -- ; then + cd ../.. + rm -rf content/releases + git worktree prune +else + echo "Directory content/releases contains uncommitted changes" + exit 1 +fi diff --git a/site/bin/run-hugo-in-docker.sh b/site/bin/run-hugo-in-docker.sh new file mode 100755 index 000000000..73639288a --- /dev/null +++ b/site/bin/run-hugo-in-docker.sh @@ -0,0 +1,51 @@ +#!/usr/bin/env bash +# +# 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. +# + +set -e + +cd "$(dirname "$0")/../.." + +# _gen is a tmpfs - must remove it first +rm -rf site/resources/_gen + +COMPOSE="$(which podman-compose > /dev/null && echo podman-compose || echo "docker-compose")" + +ARGS="" + +BIND_ARG="bind" +case "$(uname)" in + Linux) + # Needed for podman on Linux, so it doesn't "chown" the Polaris workspace to an ephemeral UID (Linux only) + BIND_ARG="bind,uid=$(id -u),gid=$(id -g)" + + if [[ ${COMPOSE} == "podman-compose" ]]; then + # Let podman use the user's UID+GID in the running container + ARGS="--podman-run-args=--userns=keep-id" + fi + ;; +esac +export BIND_ARG + +$COMPOSE \ + --project-name polaris_site \ + --file docker-compose-hugo.yml \ + $ARGS \ + up \ + --build diff --git a/site/bin/stop-hugo-in-docker.sh b/site/bin/stop-hugo-in-docker.sh new file mode 100755 index 000000000..7d5c6914f --- /dev/null +++ b/site/bin/stop-hugo-in-docker.sh @@ -0,0 +1,35 @@ +#!/usr/bin/env bash +# +# 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. +# + +set -e + +cd "$(dirname "$0")/../.." + +DOCKER="$(which docker > /dev/null && echo docker || echo podman)" +COMPOSE="$(which docker-compose > /dev/null && echo docker-compose || echo "docker-compose")" + +$COMPOSE \ + --project-name polaris_site \ + --file docker-compose-hugo.yml \ + down + +$DOCKER volume rm polaris_site_resource_gen || true +$DOCKER volume rm polaris_site_workspace || true +# keep the polaris_site_hugo_cache, which contains downloaded Go modules diff --git a/site/content/_index.adoc b/site/content/_index.adoc new file mode 100644 index 000000000..d9dec6d2c --- /dev/null +++ b/site/content/_index.adoc @@ -0,0 +1,53 @@ +--- +# +# 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. +# +title: "Apache Polaris" +type: home +cascade: + no_list: true +--- +{{< blocks/cover title="Welcome to the Apache Polaris™ (incubating) web site!" image_anchor="center" color="primary" >}} +Apache Polaris is an open-source, fully-featured catalog for Apache Iceberg™. It implements Iceberg's REST API, enabling seamless multi-engine interoperability across a wide range of platforms, including Apache Doris™, Apache Flink®, Apache Spark™, StarRocks, and Trino. +{{< /blocks/cover >}} + +image::images/Polaris-Catalog-BLOG-symmetrical-subhead.png[Polaris Catalog] + +{{< blocks/section color="dark" type="row" >}} +{{% blocks/feature icon="fa-lightbulb" title="Join the community!" url="https://polaris-catalog.zulipchat.com/" url_text="Chat with us" %}} +Chat with users and project developers! +{{% /blocks/feature %}} +{{% blocks/feature icon="fa-brands fa-github" title="Contributions welcome!" url="https://github.com/apache/polaris/pulls" url_text="Polaris Pull Requests" %}} +We do a https://github.com/apache/polaris/pulls[Pull Request] contributions workflow on **GitHub**. New users are always welcome! +{{% /blocks/feature %}} +{{% blocks/feature icon="fa fa-envelope" title="Join our mailing list" url="https://lists.apache.org/list.html?dev@polaris.apache.org" url_text="Subscribe" %}} +For announcement and discussions about the project. +{{% /blocks/feature %}} +{{< /blocks/section >}} + +{{< blocks/section color="dark" >}} +

+ +

+

+Apache Polaris™ is an effort undergoing incubation at The Apache Software Foundation (ASF), sponsored by the Apache Incubator. Incubation is required of all newly accepted projects until a further review indicates that the infrastructure, communications, and decision making process have stabilized in a manner consistent with other successful ASF projects. While incubation status is not necessarily a reflection of the completeness or stability of the code, it does indicate that the project has yet to be fully endorsed by the ASF. +

+

+Apache®, Apache Polaris™, Apache Iceberg™, Apache Spark™ are either registered trademarks or trademarks of the Apache Software Foundation in the United States and/or other countries. +

+{{< /blocks/section >}} diff --git a/site/content/basics/_index.adoc b/site/content/basics/_index.adoc new file mode 100644 index 000000000..16e49e725 --- /dev/null +++ b/site/content/basics/_index.adoc @@ -0,0 +1,88 @@ +--- +# +# 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. +# +title: "Hugo/Docsy Playground" +linkTitle: "Hugo & Docsy" +type: docs +weight: 100 +--- + +This is a new home page. + +== Nested Tables!! YAY!!!!!! + +[cols="1,2a"] +|=== +| Col 1 | Col 2 + +| Cell 1.1 +| Cell 1.2 + +| Cell 2.1 +| Cell 2.2 + +[cols="2,1"] +!=== +! Col1 ! Col2 + +! C11 +! C12 + +!=== + +|=== + +== Source Code + +=== Via Hugo + +{{< highlight java "linenos=table,hl_lines=5 7-9,linenostart=1" >}} +package org.apache.polaris.docsfoo; + +import java.util.List; + +@ApplicationScoped +public class FooBar { +public List getPolarisValues() { +return List.of("a", "lot", "of", "values"); +} +} +{{< / highlight >}} + +=== Via asciidoc + +[source,java] +---- +package org.apache.polaris.docsfoo; + +import java.util.List; + +@ApplicationScoped +public class FooBar { + public List getPolarisValues() { + return List.of("a", "lot", "of", "values"); + } +} +---- + +[source,bash] +---- +cd foo +mkdir bar +---- diff --git a/site/content/basics/fifth-content.md b/site/content/basics/fifth-content.md new file mode 100644 index 000000000..761ad1e95 --- /dev/null +++ b/site/content/basics/fifth-content.md @@ -0,0 +1,54 @@ +--- +# +# 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. +# +title: 'Shortcodes' +type: docs +date: 2024-08-30T17:51:20+02:00 +--- + +{{% blocks/lead color="dark" %}} +TechOS is the OS of the future. + +Runs on **bare metal** in the **cloud**! +{{% /blocks/lead %}} + + +{{< blocks/section color="dark" type="row" >}} +{{% blocks/feature icon="fa-lightbulb" title="Fastest OS **on the planet**!" %}} +The new **TechOS** operating system is an open source project. It is a new project, but with grand ambitions. +Please follow this space for updates! +{{% /blocks/feature %}} +{{% blocks/feature icon="fa-brands fa-github" title="Contributions welcome!" url="https://github.com/gohugoio/hugo" %}} +We do a [Pull Request](https://github.com/gohugoio/hugo/pulls) contributions workflow on **GitHub**. New users are always welcome! +{{% /blocks/feature %}} +{{% blocks/feature icon="fa-brands fa-x-twitter" title="Follow us on Twitter!" url="https://twitter.com/GoHugoIO" %}} +For announcement of latest features etc. +{{% /blocks/feature %}} +{{< /blocks/section >}} + + +{{% blocks/feature icon="fa-brands fa-github" title="Contributions welcome!" url="https://github.com/gohugoio/hugo" %}} +We do a [Pull Request](https://github.com/gohugoio/hugo/pulls) contributions workflow on **GitHub**. New users are always welcome! +{{% /blocks/feature %}} + + +{{< alert title="Warning" color="warning" >}} +This is a warning. +{{< /alert >}} + diff --git a/site/content/basics/first-content/_index.md b/site/content/basics/first-content/_index.md new file mode 100644 index 000000000..e52e391f1 --- /dev/null +++ b/site/content/basics/first-content/_index.md @@ -0,0 +1,25 @@ +--- +# +# 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. +# +title: 'First Content' +type: docs +date: 2024-08-30T17:51:20+02:00 +--- + +Empty :( diff --git a/site/content/basics/fourth-content.md b/site/content/basics/fourth-content.md new file mode 100644 index 000000000..31e6e1c41 --- /dev/null +++ b/site/content/basics/fourth-content.md @@ -0,0 +1,50 @@ +--- +# +# 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. +# +title: 'Mindmap' +type: docs +date: 2024-08-30T17:51:20+02:00 +--- + +```markmap +# markmap + +## Links + +- +- [GitHub](https://github.com/gera2ld/markmap) + +## Related + +- [coc-markmap](https://github.com/gera2ld/coc-markmap) +- [gatsby-remark-markmap](https://github.com/gera2ld/gatsby-remark-markmap) + +## Features + +- links +- **inline** ~~text~~ *styles* +- multiline + text +- `inline code` +- + ```js + console.log('code block'); + ``` +- Katex - $x = {-b \pm \sqrt{b^2-4ac} \over 2a}$ +``` diff --git a/site/content/basics/openapi.md b/site/content/basics/openapi.md new file mode 100644 index 000000000..d8b071020 --- /dev/null +++ b/site/content/basics/openapi.md @@ -0,0 +1,29 @@ +--- +# +# 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. +# +title: 'OpenAPI' +type: docs +date: 2024-08-30T17:51:20+02:00 +--- + +{{< alert title="Info" color="primary" >}} +Swaggerui fails on this page :( +{{< /alert >}} + +{{< swaggerui src="/openapi/polaris-management-service.yml" >}} diff --git a/site/content/basics/redoc.md b/site/content/basics/redoc.md new file mode 100644 index 000000000..0d7c20ac9 --- /dev/null +++ b/site/content/basics/redoc.md @@ -0,0 +1,27 @@ +--- +# +# 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. +# +title: 'Redoc' +type: docs +date: 2024-08-30T17:51:20+02:00 +--- + +See the versioned docs for the imaginary releases 0.0.1 and 0.0.2 for other examples. + +{{< redoc "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/main/examples/v2.0/yaml/petstore.yaml" >}} diff --git a/site/content/basics/second-content/index.md b/site/content/basics/second-content/index.md new file mode 100644 index 000000000..8d50246d1 --- /dev/null +++ b/site/content/basics/second-content/index.md @@ -0,0 +1,41 @@ +--- +# +# 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. +# +title: 'UML' +type: docs +date: 2024-08-30T17:51:20+02:00 +--- + +```plantuml +participant participant as Foo +actor actor as Foo1 +boundary boundary as Foo2 +control control as Foo3 +entity entity as Foo4 +database database as Foo5 +collections collections as Foo6 +queue queue as Foo7 +Foo -> Foo1 : To actor +Foo -> Foo2 : To boundary +Foo -> Foo3 : To control +Foo -> Foo4 : To entity +Foo -> Foo5 : To database +Foo -> Foo6 : To collections +Foo -> Foo7: To queue +``` diff --git a/site/content/basics/tabs.md b/site/content/basics/tabs.md new file mode 100644 index 000000000..84cc54801 --- /dev/null +++ b/site/content/basics/tabs.md @@ -0,0 +1,82 @@ +--- +# +# 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. +# +title: 'Tabs' +type: docs +date: 2024-08-30T17:51:20+02:00 +--- + +{{< tabpane text=true left=true >}} + {{% tab header="**Languages**:" disabled=true /%}} + {{% tab header="English" lang="en" %}} + Welcome! + {{% /tab %}} + {{< tab header="German" lang="de" >}} + Herzlich willkommen! + {{< /tab >}} + {{% tab header="Swahili" lang="sw" %}} + **Karibu sana!** + {{% /tab %}} +{{< /tabpane >}} + +{{< tabpane left=true langEqualsHeader=true >}} + {{% tab header="**Code in**:" disabled=true /%}} + {{% tab header="Java" text=true %}} +Initial text + +```java +String foo = "bar"; +``` + +More text + {{< /tab >}} + {{% tab header="Python" text=true %}} +Some more markdown text... + +```python +class ApiClient: + PRIMITIVE_TYPES = (float, bool, bytes, str, int) +``` + +Hello World! + {{% /tab %}} + {{% tab header="Go" text=true %}} +Some code in Go + +```go +foo = "bar"; +``` + +More more + {{% /tab %}} +{{< /tabpane >}} + +{{< tabpane left=true langEqualsHeader=true >}} + {{% tab header="**More code in**:" disabled=true /%}} + {{< tab header="Java" >}} + String bar = "baz"; + {{< /tab >}} + {{< tab header="Python" >}} + class ApiClient: + PRIMITIVE_TYPES = (float, bool, bytes, str, int) + {{< /tab >}} + {{< tab header="Go" >}} + bar = "baz"; + {{< /tab >}} +{{< /tabpane >}} diff --git a/site/content/basics/third-content.md b/site/content/basics/third-content.md new file mode 100644 index 000000000..ec850c5c7 --- /dev/null +++ b/site/content/basics/third-content.md @@ -0,0 +1,39 @@ +--- +# +# 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. +# +title: 'Sequence Diagram' +type: docs +date: 2024-08-30T17:51:20+02:00 +--- + +```mermaid +sequenceDiagram + autonumber + Docsy user->>Discussion board: Ask question + Discussion board->>Community member: read question + loop Different strategies + Community member->>Test instance: Investigate issue raised + end + Note right of Community member: After hours of investigation: + Test instance-->>Community member: Come up with solution + Community member-->>Discussion board: Propose solution + Discussion board-->>Docsy user: check proposed solution + Docsy user->>Discussion board: Mark question as resolved + Docsy user->>Docsy user: Being happy +``` diff --git a/site/content/blog/2024/09/02/first-blog.md b/site/content/blog/2024/09/02/first-blog.md new file mode 100644 index 000000000..656b729bb --- /dev/null +++ b/site/content/blog/2024/09/02/first-blog.md @@ -0,0 +1,33 @@ +--- +# +# 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. +# +title: "My first blog post" +date: 2024-08-01T17:51:20+02:00 +--- + +# My first blog post + +My first blog post + +My first blog post + +My first blog post + +My first blog postMy first blog postMy first blog postMy first blog postMy first blog postMy first blog postMy first +blog postMy first blog post \ No newline at end of file diff --git a/site/content/blog/2024/09/02/second-blog.md b/site/content/blog/2024/09/02/second-blog.md new file mode 100644 index 000000000..c2850375e --- /dev/null +++ b/site/content/blog/2024/09/02/second-blog.md @@ -0,0 +1,33 @@ +--- +# +# 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. +# +title: "My second blog post" +date: 2024-08-02T17:51:20+02:00 +--- + +# My second blog post + +My first blog post + +My first blog post + +My first blog post + +My first blog postMy first blog postMy first blog postMy first blog postMy first blog postMy first blog postMy first +blog postMy first blog post \ No newline at end of file diff --git a/site/content/blog/_index.adoc b/site/content/blog/_index.adoc new file mode 100644 index 000000000..a39e9d91c --- /dev/null +++ b/site/content/blog/_index.adoc @@ -0,0 +1,27 @@ +--- +# +# 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. +# +linkTitle: "Blog" +title: "Apache Polaris Blog" +weight: 200 +cascade: + - type: "blog" +--- + += Blog diff --git a/site/content/chat-bylaws.md b/site/content/chat-bylaws.md new file mode 120000 index 000000000..b28aebe2c --- /dev/null +++ b/site/content/chat-bylaws.md @@ -0,0 +1 @@ +../../CHAT_BYLAWS.md \ No newline at end of file diff --git a/site/content/code-of-conduct.md b/site/content/code-of-conduct.md new file mode 120000 index 000000000..a3613c99f --- /dev/null +++ b/site/content/code-of-conduct.md @@ -0,0 +1 @@ +../../CODE_OF_CONDUCT.md \ No newline at end of file diff --git a/site/content/community/_index.adoc b/site/content/community/_index.adoc new file mode 100644 index 000000000..f276cf1da --- /dev/null +++ b/site/content/community/_index.adoc @@ -0,0 +1,89 @@ +--- +# +# 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. +# +linkTitle: 'Community' +title: 'Apache Polaris Community' +weight: 300 +params: + contributingUrl: "/community/contributing-guidelines" +--- + +{{< blocks/section color="white" type="row" >}} +{{% blocks/feature icon="fa-solid fa-graduation-cap" title="Learn, Connect and Collaborate" %}} +[cols="2,3"] +|=== +| link:https://polaris-catalog.zulipchat.com/[Zulip] +| Our public chat, open to everybody + +| link:./meetings/[Community Meetings] +| Upcoming, live and recorded Community Meetings + +| link:./proposals/[Proposals] +| Proposals about bigger topics + +| link:https://github.com/apache/polaris[GitHub] +| Development takes place here! + +| link:./code-of-conduct/[Code of Conduct] +| Code of Conduct + +| link:./chat-bylaws/[Chat Bylaws] +| A few rules around our public chat as a collaboration tool for the project. + +| link:./contributing-guidelines/[Contribution Guidelines] +| How to contribute to Apache Polaris +|=== +{{% /blocks/feature %}} + +{{% blocks/feature icon="fa fa-envelope" title="All Mailing Lists" %}} +[cols="3,3"] +|=== +| Development oriented content +| mailto:dev-subscribe@polaris.apache.org[Subscribe to dev@] + + link:https://lists.apache.org/list.html?polaris.apache.org[Mailing List Archives,window=_blank] +| Notifications about GitHub issues and PRs +| mailto:issues-subscribe@polaris.apache.org[Subscribe to issues@] + + link:https://lists.apache.org/list.html?polaris.apache.org[Mailing List Archives,window=_blank] +| Notifications about Git commits +| mailto:commits-subscribe@polaris.apache.org[Subscribe to commits@] + + link:https://lists.apache.org/list.html?polaris.apache.org[Mailing List Archives,window=_blank] +|=== +{{% /blocks/feature %}} + +{{% blocks/feature icon="fa-solid fa-people-group" title="Team" %}} +[cols="4,1,3"] +|=== +| Anoop Johnson | PPMC | link:https://www.google.com/[Google] +| https://github.com/ashvina[Ashvin Agrawal] | PPMC | link:https://www.microsoft.com/[Microsoft] +| Bertrand Delacretaz | Mentor | +| Holden Karau | Mentor | +| https://github.com/jackye1995[Jack Ye] | PPMC | link:https://aws.amazon.com/[Amazon] +| https://github.com/jbonofre[JB Onofre] | PPMC & Mentor | link:https://www.dremio.com/[Dremio] +| https://github.com/vvcephei[John Roesler] | PPMC | link:https://www.confluent.io/[Confluent] +| Kent Yao | Mentor | +| https://github.com/snazy[Robert Stupp] | PPMC | link:https://www.dremio.com/[Dremio] +| https://github.com/russellspitzer[Russell Spitzer] | PPMC | link:https://www.snowflake.com/[Snowflake] +| Ryan Blue | Mentor | +| https://github.com/takidau:[Tyler Akidau] | PPMC | link:https://www.snowflake.com/[Snowflake] +|=== +{{% /blocks/feature %}} +{{< /blocks/section >}} diff --git a/site/content/community/chat-bylaws.md b/site/content/community/chat-bylaws.md new file mode 100644 index 000000000..520732e18 --- /dev/null +++ b/site/content/community/chat-bylaws.md @@ -0,0 +1,25 @@ +--- +# +# 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. +# +linkTitle: Chat Bylaws +type: docs +weight: 400 +--- + +{{< readfile "/chat-bylaws.md" >}} diff --git a/site/content/community/code-of-conduct.md b/site/content/community/code-of-conduct.md new file mode 100644 index 000000000..060fe605e --- /dev/null +++ b/site/content/community/code-of-conduct.md @@ -0,0 +1,25 @@ +--- +# +# 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. +# +linkTitle: Code Of Conduct +type: docs +weight: 300 +--- + +{{< readfile "/code-of-conduct.md" >}} diff --git a/site/content/community/contributing-guidelines.md b/site/content/community/contributing-guidelines.md new file mode 100644 index 000000000..8b9339059 --- /dev/null +++ b/site/content/community/contributing-guidelines.md @@ -0,0 +1,25 @@ +--- +# +# 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. +# +linkTitle: Contributing Guidelines +type: docs +weight: 500 +--- + +{{< readfile "/contributing-to-polaris.md" >}} diff --git a/site/content/community/meetings/2024/_index.adoc b/site/content/community/meetings/2024/_index.adoc new file mode 100644 index 000000000..bb3b2218a --- /dev/null +++ b/site/content/community/meetings/2024/_index.adoc @@ -0,0 +1,41 @@ +--- +# +# 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. +# +linkTitle: '2024' +title: 'Apache Polaris Community Meetings in 2024' +--- + +== Upcoming Meetings + +https://polaris.apache.org/[Agenda for upcoming Community Meetings] + +== Past Meetings + +[cols="1,3,3"] +|=== +| Date | Notes | Recording + +| 2024-08-29 +| Meeting Notes 1 +| {{< youtube id=w7Ft2ymGmfc loading=lazy title="Not a Polaris meeting" >}} + +| 2024-08-30 +| Meeting Notes 2 +| {{< youtube id=w7Ft2ymGmfc loading=lazy title="Not a Polaris meeting" >}} +|=== diff --git a/site/content/community/meetings/_index.adoc b/site/content/community/meetings/_index.adoc new file mode 100644 index 000000000..318df290d --- /dev/null +++ b/site/content/community/meetings/_index.adoc @@ -0,0 +1,26 @@ +--- +# +# 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. +# +linkTitle: 'Meetings' +title: 'Apache Polaris Community Meetings' +weight: 100 +cascade: + type: docs + no_list: false +--- diff --git a/site/content/community/proposals.adoc b/site/content/community/proposals.adoc new file mode 100644 index 000000000..2bd512a41 --- /dev/null +++ b/site/content/community/proposals.adoc @@ -0,0 +1,53 @@ +--- +# +# 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. +# +linkTitle: 'Proposals' +title: 'Apache Polaris Proposals' +weight: 200 +type: docs +--- + +== Active Proposals + +[cols="4,2,4,4"] +|=== +| Topic | Date Created | Proposal Document | Dev-list discussion + +| Sample topic placeholder +| 2024/09/06 +| Link to Google Doc +| Link to dev-mailing list discussion + +|=== + + +== Previous Proposals + + +[cols="4,2,4,4,2"] +|=== +| Topic | Date Created | Proposal Document | Dev-list discussion + vote | Resolution + +| Sample topic placeholder +| 2024/09/06 +| Link to Google Doc +| Link to dev-mailing list discussion +| Accepted + +|=== diff --git a/site/content/contributing-to-polaris.md b/site/content/contributing-to-polaris.md new file mode 120000 index 000000000..f939e75f2 --- /dev/null +++ b/site/content/contributing-to-polaris.md @@ -0,0 +1 @@ +../../CONTRIBUTING.md \ No newline at end of file diff --git a/site/content/guides/_index.adoc b/site/content/guides/_index.adoc new file mode 100644 index 000000000..49669d7ef --- /dev/null +++ b/site/content/guides/_index.adoc @@ -0,0 +1,27 @@ +--- +# +# 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. +# +linkTitle: "Guides" +title: "Apache Polaris Guides" +weight: 200 +cascade: + type: docs +--- + += Guides diff --git a/site/content/in-dev/_index.md b/site/content/in-dev/_index.md new file mode 100644 index 000000000..d3682b20f --- /dev/null +++ b/site/content/in-dev/_index.md @@ -0,0 +1,24 @@ +--- +# +# 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. +# +# Hide `/in-dev/` +toc_hide: true +hide_summary: true +exclude_search: true +--- diff --git a/site/content/in-dev/release_index.md b/site/content/in-dev/release_index.md new file mode 100644 index 000000000..50ab7e11e --- /dev/null +++ b/site/content/in-dev/release_index.md @@ -0,0 +1,31 @@ +--- +# +# 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. +# +title: 'POLARIS VERSION INDEX MD TEMPLATE' +toc_hide: true +hide_summary: true +cascade: + # The latest release specifies 'false', all others must be 'true' + exclude_search: false +# This file will be copied as `_index.md` into a new release's versioned docs folder. +--- + +== Apache Polaris version {{< releaseVersion >}} + +Download from ... diff --git a/site/content/in-dev/unreleased/_index.md b/site/content/in-dev/unreleased/_index.md new file mode 100644 index 000000000..84fec714a --- /dev/null +++ b/site/content/in-dev/unreleased/_index.md @@ -0,0 +1,37 @@ +--- +# +# 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. +# +linkTitle: 'In Development' +title: 'Unreleased - current state of the main branch' +type: docs +weight: 200 +params: + top_hidden: true +cascade: + type: docs +# This file will NOT be copied into a new release's versioned docs folder. +--- + +{{< alert title="Warning" color="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 >}} + +Testing the `releaseVersion` shortcode here: version is: {{< releaseVersion >}} diff --git a/site/content/in-dev/unreleased/documentation/_index.md b/site/content/in-dev/unreleased/documentation/_index.md new file mode 100644 index 000000000..7f975f731 --- /dev/null +++ b/site/content/in-dev/unreleased/documentation/_index.md @@ -0,0 +1,228 @@ +--- +# +# 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. +# +Title: Overview +type: docs +weight: 200 +--- + + +Apache Polaris (Incubating) is a catalog implementation for Apache Iceberg™ tables and is built on the open source Apache Iceberg™ REST protocol. + +With Polaris, you can provide centralized, secure read and write access to your Iceberg tables across different REST-compatible query engines. + +![Conceptual diagram of Apache Polaris (Incubating).](/img/overview.svg "Apache Polaris (Incubating) overview") + +## Key concepts + +This section introduces key concepts associated with using Apache Polaris (Incubating). + +In the following diagram, a sample [Apache Polaris (Incubating) structure](overview.md#catalog) with nested [namespaces](overview.md#namespace) is shown for Catalog1. No tables +or namespaces have been created yet for Catalog2 or Catalog3. + +![Diagram that shows an example Apache Polaris (Incubating) structure.](/img/sample-catalog-structure.svg "Sample Apache Polaris (Incubating) structure") + +### Catalog + +In Polaris, you can create one or more catalog resources to organize Iceberg tables. + +Configure your catalog by setting values in the storage configuration for S3, Azure, or Google Cloud Storage. An Iceberg catalog enables a +query engine to manage and organize tables. The catalog forms the first architectural layer in the [Apache Iceberg™ table specification](https://iceberg.apache.org/spec/#overview) and must support the following tasks: + +- Storing the current metadata pointer for one or more Iceberg tables. A metadata pointer maps a table name to the location of that table's + current metadata file. + +- Performing atomic operations so that you can update the current metadata pointer for a table to the metadata pointer of a new version of + the table. + +To learn more about Iceberg catalogs, see the [Apache Iceberg™ documentation](https://iceberg.apache.org/concepts/catalog/). + +#### Catalog types + +A catalog can be one of the following two types: + +- Internal: The catalog is managed by Polaris. Tables from this catalog can be read and written in Polaris. + +- External: The catalog is externally managed by another Iceberg catalog provider (for example, Snowflake, Glue, Dremio Arctic). Tables from + this catalog are synced to Polaris. These tables are read-only in Polaris. In the current release, only a Snowflake external catalog is provided. + +A catalog is configured with a storage configuration that can point to S3, Azure storage, or GCS. + +### Namespace + +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. + +### Apache Iceberg™ tables and catalogs + +In an internal catalog, an Iceberg table is registered in Polaris, but read and written via query engines. The table data and +metadata is stored in your external cloud storage. The table uses Polaris as the Iceberg catalog. + +If you have tables that use Snowflake as the Iceberg catalog (Snowflake-managed tables), you can sync these tables to an external +catalog in Polaris. If you sync this catalog to Polaris, it appears as an external catalog in Polaris. The table data and +metadata is stored in your external cloud storage. The Snowflake query engine can read from or write to these tables. However, the other query +engines can only read from these tables. + +> **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/ +> - /namespace1/namespace1a/orders/ + +### Service principal + +A service principal is an entity that you create in Polaris. Each service principal encapsulates credentials that you use to connect +to Polaris. + +Query engines use service principals to connect to catalogs. + +Polaris generates a Client ID and Client Secret pair for each service principal. + +The following table displays example service principals that you might create in Polaris: + + | Service connection name | Purpose | + | --------------------------- | ----------- | + | Flink ingestion | For Apache Flink® to ingest streaming data into Apache Iceberg™ tables. | + | Spark ETL pipeline | For Apache Spark™ to run ETL pipeline jobs on Iceberg tables. | + | Snowflake data pipelines | For Snowflake to run data pipelines for transforming data in Apache Iceberg™ tables. | + | Trino BI dashboard | For Trino to run BI queries for powering a dashboard. | + | Snowflake AI team | For Snowflake to run AI jobs on data in Apache Iceberg™ tables. | + +### Service connection + +A service connection represents a REST-compatible engine (such as Apache Spark™, Apache Flink®, or Trino) that can read from and write to Polaris +Catalog. When creating a new service connection, the Polaris administrator grants the service principal that is created with the new service +connection either a new or existing principal role. A principal role is a resource in Polaris that you can use to logically group Polaris +service principals together and grant privileges on securable objects. For more information, see [Principal role](access-control.md#principal-role "Principal role"). Polaris uses a role-based access control (RBAC) model to grant service principals access to resources. For more information, +see [Access control](access-control.md "Access control"). For a diagram of this model, see [RBAC model](access-control.md#rbac-model "RBAC model"). + +If the Polaris administrator grants the service principal for the new service connection a new principal role, the service principal +doesn't have any privileges granted to it yet. When securing the catalog that the new service connection will connect to, the Polaris +administrator grants privileges to catalog roles and then grants these catalog roles to the new principal role. As a result, the service +principal for the new service connection has these privileges. For more information about catalog roles, see [Catalog role](access-control.md#catalog-role "Catalog role"). + +If the Polaris administrator grants an existing principal role to the service principal for the new service connection, the service principal +has the same privileges granted to the catalog roles that are granted to the existing principal role. If needed, the Polaris +administrator can grant additional catalog roles to the existing principal role or remove catalog roles from it to adjust the privileges +bestowed to the service principal. For an example of how RBAC works in Polaris, see [RBAC example](access-control.md#rbac-example "RBAC example"). + +### Storage configuration + +A storage configuration stores a generated identity and access management (IAM) entity for your external cloud storage and is created +when you create a catalog. The storage configuration is used to set the values to connect Polaris to your cloud storage. During the +catalog creation process, an IAM entity is generated and used to create a trust relationship between the cloud storage provider and Polaris +Catalog. + +When you create a catalog, you supply the following information about your external cloud storage: + +| Cloud storage provider | Information | +| -----------------------| ----------- | +| Amazon S3 |
  • Default base location for your Amazon S3 bucket
  • Locations for your Amazon S3 bucket
  • S3 role ARN
  • External ID (optional)
| +| Google Cloud Storage (GCS) |
  • Default base location for your GCS bucket
  • Locations for your GCS bucket
| +| Azure |
  • Default base location for your Microsoft Azure container
  • Locations for your Microsoft Azure container
  • Azure tenant ID
| + +## Example workflow + +In the following example workflow, Bob creates an Apache Iceberg™ table named Table1 and Alice reads data from Table1. + +1. Bob uses Apache Spark™ to create the Table1 table under the + Namespace1 namespace in the Catalog1 catalog and insert values into + Table1. + + Bob can create Table1 and insert data into it because he is using a + service connection with a service principal that has + the privileges to perform these actions. + +2. Alice uses Snowflake to read data from Table1. + + Alice can read data from Table1 because she is using a service + connection with a service principal with a catalog integration that + has the privileges to perform this action. Alice + creates an unmanaged table in Snowflake to read data from Table1. + +![Diagram that shows an example workflow for Apache Polaris (Incubating)](/img/example-workflow.svg "Example workflow for Apache Polaris (Incubating)") + +## Security and access control + +This section describes security and access control. + +### Credential vending + +To secure interactions with service connections, Polaris vends temporary storage credentials to the query engine during query +execution. These credentials allow the query engine to run the query without requiring access to your external cloud storage for +Iceberg tables. This process is called credential vending. + +### Identity and access management (IAM) + +Polaris uses the identity and access management (IAM) entity to securely connect to your storage for accessing table data, Iceberg +metadata, and manifest files that store the table schema, partitions, and other metadata. Polaris retains the IAM entity for your +storage location. + +### Access control + +Polaris enforces the access control that you configure across all tables registered with the service and governs security for all +queries from query engines in a consistent manner. + +Polaris uses a role-based access control (RBAC) model that lets you centrally configure access for Polaris service principals to catalogs, +namespaces, and tables. + +Polaris RBAC uses two different role types to delegate privileges: + +- **Principal roles:** Granted to Polaris service principals and + analogous to roles in other access control systems that you grant to + service principals. + +- **Catalog roles:** Configured with certain privileges on Polaris + catalog resources and granted to principal roles. + +For more information, see [Access control](access-control.md "Access control"). + +## Legal Notices + +Apache®, Apache Iceberg™, Apache Spark™, Apache Flink®, and Flink® are either registered trademarks or trademarks of the Apache Software Foundation in the United States and/or other countries. diff --git a/site/content/in-dev/unreleased/documentation/access-control.md b/site/content/in-dev/unreleased/documentation/access-control.md new file mode 100644 index 000000000..622c752af --- /dev/null +++ b/site/content/in-dev/unreleased/documentation/access-control.md @@ -0,0 +1,211 @@ +--- +# +# 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. +# +Title: Access Control +type: docs +weight: 400 +--- + + +This section provides information about how access control works for Apache Polaris (Incubating). + +Polaris uses a role-based access control (RBAC) model in which the Polaris administrator assigns access privileges to catalog roles +and then grants access to resources to service principals by assigning catalog roles to principal roles. + +These are the key concepts to understanding access control in Polaris: + +- **Securable object** +- **Principal role** +- **Catalog role** +- **Privilege** + +## Securable object + +A securable object is an object to which access can be granted. Polaris +has the following securable objects: + +- Catalog +- Namespace +- Iceberg table +- View + +## Principal role + +A principal role is a resource in Polaris that you can use to logically group Polaris service principals together and grant privileges on +securable objects. + +Polaris supports a many-to-one relationship between service principals and principal roles. For example, to grant the same privileges to +multiple service principals, you can grant a single principal role to those service principals. A service principal can be granted one +principal role. When registering a service connection, the Polaris administrator specifies the principal role that is granted to the +service principal. + +You don't grant privileges directly to a principal role. Instead, you configure object permissions at the catalog role level, and then grant +catalog roles to a principal role. + +The following table shows examples of principal roles that you might configure in Polaris: + +| Principal role name | Description | +| -----------------------| ----------- | +| Data_engineer | A role that is granted to multiple service principals for running data engineering jobs. | +| Data_scientist | A role that is granted to multiple service principals for running data science or AI jobs. | + +## Catalog role + +A catalog role belongs to a particular catalog resource in Polaris and specifies a set of permissions for actions on the catalog or objects +in the catalog, such as catalog namespaces or tables. You can create one or more catalog roles for a catalog. + +You grant privileges to a catalog role and then grant the catalog role to a principal role to bestow the privileges to one or more service +principals. + +> **Note** +> +> If you update the privileges bestowed to a service principal, the updates won't take effect for up to one hour. This means that if you +> revoke or grant some privileges for a catalog, the updated privileges won't take effect on any service principal with access to that catalog +> for up to one hour. + +Polaris also supports a many-to-many relationship between catalog roles and principal roles. You can grant the same catalog role to one or more +principal roles. Likewise, a principal role can be granted to one or more catalog roles. + +The following table displays examples of catalog roles that you might +configure in Polaris: + +| Example Catalog role | Description | +| -----------------------| ----------- | +| Catalog administrators | A role that has been granted multiple privileges to emulate full access to the catalog.

Principal roles that have been granted this role are permitted to create, alter, read, write, and drop tables in the catalog. | +| Catalog readers | A role that has been granted read-only privileges to tables in the catalog.

Principal roles that have been granted this role are allowed to read from tables in the catalog. | +| Catalog contributor | A role that has been granted read and write access privileges to all tables that belong to the catalog.

Principal roles that have been granted this role are allowed to perform read and write operations on tables in the catalog. | + +## RBAC model + +The following diagram illustrates the RBAC model used by Polaris. For each catalog, the Polaris administrator assigns access +privileges to catalog roles and then grants service principals access to resources by assigning catalog roles to principal roles. Polaris +supports a many-to-one relationship between service principals and principal roles. + +![Diagram that shows the RBAC model for Apache Polaris.](/img/rbac-model.svg "Apache Polaris RBAC model") + +## Access control privileges + +This section describes the privileges that are available in the Polaris access control model. Privileges are granted to catalog roles, catalog +roles are granted to principal roles, and principal roles are granted to service principals to specify the operations that service principals can +perform on objects in Polaris. + +> **Important** +> +> You can only grant privileges at the catalog level. Fine-grained access controls are not available. For example, you can grant read +> privileges to all tables in a catalog but not to an individual table in the catalog. + +To grant the full set of privileges (drop, list, read, write, etc.) on an object, you can use the *full privilege* option. + +### Table privileges + +| Privilege | Description | +| --------- | ----------- | +| TABLE_CREATE | Enables registering a table with the catalog. | +| TABLE_DROP | Enables dropping a table from the catalog. | +| TABLE_LIST | Enables listing any tables in the catalog. | +| TABLE_READ_PROPERTIES | Enables reading [properties](https://iceberg.apache.org/docs/nightly/configuration/#table-properties) of the table. | +| TABLE_WRITE_PROPERTIES | Enables configuring [properties](https://iceberg.apache.org/docs/nightly/configuration/#table-properties) for the table. | +| TABLE_READ_DATA | Enables reading data from the table by receiving short-lived read-only storage credentials from the catalog. | +| TABLE_WRITE_DATA | Enables writing data to the table by receiving short-lived read+write storage credentials from the catalog. | +| TABLE_FULL_METADATA | Grants all table privileges, except TABLE_READ_DATA and TABLE_WRITE_DATA, which need to be granted individually. | + +### View privileges + +| Privilege | Description | +| --------- | ----------- | +| VIEW_CREATE | Enables registering a view with the catalog. | +| VIEW_DROP | Enables dropping a view from the catalog. | +| VIEW_LIST | Enables listing any views in the catalog. | +| VIEW_READ_PROPERTIES | Enables reading all the view properties. | +| VIEW_WRITE_PROPERTIES | Enables configuring view properties. | +| VIEW_FULL_METADATA | Grants all view privileges. | + +### Namespace privileges + +| Privilege | Description | +| --------- | ----------- | +| NAMESPACE_CREATE | Enables creating a namespace in a catalog. | +| NAMESPACE_DROP | Enables dropping the namespace from the catalog. | +| NAMESPACE_LIST | Enables listing any object in the namespace, including nested namespaces and tables. | +| NAMESPACE_READ_PROPERTIES | Enables reading all the namespace properties. | +| NAMESPACE_WRITE_PROPERTIES | Enables configuring namespace properties. | +| NAMESPACE_FULL_METADATA | Grants all namespace privileges. | + +### Catalog privileges + +| Privilege | Description | +| -----------------------| ----------- | +| CATALOG_MANAGE_ACCESS | Includes the ability to grant or revoke privileges on objects in a catalog to catalog roles, and the ability to grant or revoke catalog roles to or from principal roles. | +| CATALOG_MANAGE_CONTENT | Enables full management of content for the catalog. This privilege encompasses the following privileges:
  • CATALOG_MANAGE_METADATA
  • TABLE_FULL_METADATA
  • NAMESPACE_FULL_METADATA
  • VIEW_FULL_METADATA
  • TABLE_WRITE_DATA
  • TABLE_READ_DATA
  • CATALOG_READ_PROPERTIES
  • CATALOG_WRITE_PROPERTIES
| +| CATALOG_MANAGE_METADATA | Enables full management of the catalog, catalog roles, namespaces, and tables. | +| CATALOG_READ_PROPERTIES | Enables listing catalogs and reading properties of the catalog. | +| CATALOG_WRITE_PROPERTIES | Enables configuring catalog properties. | + +## RBAC example + +The following diagram illustrates how RBAC works in Polaris and +includes the following users: + +- **Alice:** A service admin who signs up for Polaris. Alice can + create service principals. She can also create catalogs and + namespaces and configure access control for Polaris resources. + +- **Bob:** A data engineer who uses Snowpipe Streaming (in Snowflake) + and Apache Spark™ connections to interact with Polaris. + + - Alice has created a service principal for Bob. It has been + granted the Data_engineer principal role, which in turn has been + granted the following catalog roles: Catalog contributor and + Data administrator (for both the Silver and Gold zone catalogs + in the following diagram). + + - The Catalog contributor role grants permission to create + namespaces and tables in the Bronze zone catalog. + + - The Data administrator roles grant full administrative rights to + the Silver zone catalog and Gold zone catalog. + +- **Mark:** A data scientist who uses Snowflake AI services to + interact with Polaris. + + - Alice has created a service principal for Mark. It has been + granted the Data_scientist principal role, which in turn has + been granted the catalog role named Catalog reader. + + - The Catalog reader role grants read-only access for a catalog + named Gold zone catalog. + +![Diagram that shows an example of how RBAC works in Apache Polaris.](/img/rbac-example.svg "Apache Polaris RBAC example") diff --git a/site/content/in-dev/unreleased/documentation/command-line-interface.md b/site/content/in-dev/unreleased/documentation/command-line-interface.md new file mode 100644 index 000000000..93e107516 --- /dev/null +++ b/site/content/in-dev/unreleased/documentation/command-line-interface.md @@ -0,0 +1,1106 @@ +--- +# +# 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. +# +linkTitle: Command Line Interface +title: Apache Polaris (Incubating) CLI +type: docs +weight: 200 +--- + + +In order to help administrators quickly set up and manage their Polaris server, Polaris provides a simple command-line interface (CLI) for common tasks. + +The basic syntax of the Polaris CLI is outlined below: + +``` +polaris [options] COMMAND ... + +options: +--host +--port +--client-id +--client-secret +``` + +`COMMAND` must be one of the following: +1. catalogs +2. principals +3. principal-roles +4. catalog-roles +5. namespaces +6. privileges + +Each _command_ supports several _subcommands_, and some _subcommands_ have _actions_ that come after the subcommand in turn. Finally, _arguments_ follow to form a full invocation. Within a set of named arguments at the end of an invocation ordering is generally not important. Many invocations also have a required positional argument of the type that the _command_ refers to. Again, the ordering of this positional argument relative to named arguments is not important. + +Some example full invocations: + +``` +polaris principals list +polaris catalogs delete some_catalog_name +polaris catalogs update --property foo=bar some_other_catalog +polaris catalogs update another_catalog --property k=v +polaris privileges namespace grant --namespace some.schema --catalog fourth_catalog --catalog-role some_catalog_role TABLE_READ_DATA +``` + +### Authentication + +As outlined above, the Polaris CLI may take credentials using the `--client-id` and `--client-secret` options. For example: + +``` +polaris --client-id 4b5ed1ca908c3cc2 --client-secret 07ea8e4edefb9a9e57c247e8d1a4f51c principals ... +``` + +If `--client-id` and `--client-secret` are not provided, the Polaris CLI will try to read the client ID and client secret from environment variables called `CLIENT_ID` and `CLIENT_SECRET` respectively. If these flags are not provided and the environment variables are not set, the CLI will fail. + +If the `--host` and `--port` options are not provided, the CLI will default to communicating with `localhost:8181`. + +### PATH + +These examples assume the Polaris CLI is on the PATH and so can be invoked just by the command `polaris`. You can add the CLI to your PATH environment variable with a command like the following: + +``` +export PATH="~/polaris:$PATH" +``` + +Alternatively, you can run the CLI by providing a path to it, such as with the following invocation: + +``` +~/polaris principals list +``` + +## Commands + +Each of the commands `catalogs`, `principals`, `principal-roles`, `catalog-roles`, and `privileges` is used to manage a different type of entity within Polaris. + +To find details on the options that can be provided to a particular command or subcommand ad-hoc, you may wish to use the `--help` flag. For example: + +``` +polaris catalogs --help +polaris principals create --help +``` + +### catalogs + +The `catalogs` command is used to create, discover, and otherwise manage catalogs within Polaris. + +`catalogs` supports the following subcommands: + +1. create +2. delete +3. get +4. list +5. update + +#### create + +The `create` subcommand is used to create a catalog. + +``` +input: polaris catalogs create --help +options: + create + Named arguments: + --type The type of catalog to create in [INTERNAL, EXTERNAL]. INTERNAL by default. + --storage-type (Required) The type of storage to use for the catalog + --default-base-location (Required) Default base location of the catalog + --allowed-location An allowed location for files tracked by the catalog. Multiple locations can be provided by specifying this option more than once. + --role-arn (Required for S3) A role ARN to use when connecting to S3 + --external-id (Only for S3) The external ID to use when connecting to S3 + --tenant-id (Required for Azure) A tenant ID to use when connecting to Azure Storage + --multi-tenant-app-name (Only for Azure) The app name to use when connecting to Azure Storage + --consent-url (Only for Azure) A consent URL granting permissions for the Azure Storage location + --service-account (Only for GCS) The service account to use when connecting to GCS + --remote-url (For external catalogs) The remote URL to use + --property A key/value pair such as: tag=value. Multiple can be provided by specifying this option more than once + Positional arguments: + catalog +``` + +##### Examples + +``` +polaris catalogs create \ + --storage-type s3 \ + --default-base-location s3://example-bucket/my_data \ + --role-arn ${ROLE_ARN} \ + my_catalog + +polaris catalogs create \ + --storage-type s3 \ + --default-base-location s3://example-bucket/my_other_data \ + --allowed-location s3://example-bucket/second_location \ + --allowed-location s3://other-bucket/third_location \ + --role-arn ${ROLE_ARN} \ + my_other_catalog +``` + +#### delete + +The `delete` subcommand is used to delete a catalog. + +``` +input: polaris catalogs delete --help +options: + delete + Positional arguments: + catalog +``` + +##### Examples + +``` +polaris catalogs delete some_catalog +``` + +#### get + +The `get` subcommand is used to retrieve details about a catalog. + +``` +input: polaris catalogs get --help +options: + get + Positional arguments: + catalog +``` + +##### Examples + +``` +polaris catalogs get some_catalog + +polaris catalogs get another_catalog +``` + +#### list + +The `list` subcommand is used to show details about all catalogs, or those that a certain principal role has access to. The principal used to perform this operation must have the `CATALOG_LIST` privilege. + +``` +input: polaris catalogs list --help +options: + list + Named arguments: + --principal-role The name of a principal role +``` + +##### Examples + +``` +polaris catalogs list + +polaris catalogs list --principal-role some_user +``` + +#### update + +The `update` subcommand is used to update a catalog. Currently, this command supports changing the properties of a catalog or updating its storage configuration. + +``` +input: polaris catalogs update --help +options: + update + Named arguments: + --default-base-location (Required) Default base location of the catalog + --allowed-location An allowed location for files tracked by the catalog. Multiple locations can be provided by specifying this option more than once. + --property A key/value pair such as: tag=value. Multiple can be provided by specifying this option more than once + Positional arguments: + catalog +``` + +##### Examples + +``` +polaris catalogs update --property tag=new_value my_catalog + +polaris catalogs update --default-base-location s3://new-bucket/my_data my_catalog +``` + +### Principals + +The `principals` command is used to manage principals within Polaris. + +`principals` supports the following subcommands: + +1. create +2. delete +3. get +4. list +5. rotate-credentials +6. update + +#### create + +The `create` subcommand is used to create a new principal. + +``` +input: polaris principals create --help +options: + create + Named arguments: + --type The type of principal to create in [SERVICE] + --property A key/value pair such as: tag=value. Multiple can be provided by specifying this option more than once + Positional arguments: + principal +``` + +##### Examples + +``` +polaris principals create some_user + +polaris principals create --client-id ${CLIENT_ID} --property admin=true some_admin_user +``` + +#### delete + +The `delete` subcommand is used to delete a principal. + +``` +input: polaris principals delete --help +options: + delete + Positional arguments: + principal +``` + +##### Examples + +``` +polaris principals delete some_user + +polaris principals delete some_admin_user +``` + +#### get + +The `get` subcommand retrieves details about a principal. + +``` +input: polaris principals get --help +options: + get + Positional arguments: + principal +``` + +##### Examples + +``` +polaris principals get some_user + +polaris principals get some_admin_user +``` + +#### list + +The `list` subcommand shows details about all principals. + +##### Examples + +``` +polaris principals list +``` + +#### rotate-credentials + +The `rotate-credentials` subcommand is used to update the credentials used by a principal. After this command runs successfully, the new credentials will be printed to stdout. + +``` +input: polaris principals rotate-credentials --help +options: + rotate-credentials + Positional arguments: + principal +``` + +##### Examples + +``` +polaris principals rotate-credentials some_user + +polaris principals rotate-credentials some_admin_user +``` + +#### update + +The `update` subcommand is used to update a principal. Currently, this supports rewriting the properties associated with a principal. + +``` +input: polaris principals update --help +options: + update + Named arguments: + --property A key/value pair such as: tag=value. Multiple can be provided by specifying this option more than once + Positional arguments: + principal +``` + +##### Examples + +``` +polaris principals update --property key=value --property other_key=other_value some_user + +polaris principals update --property are_other_keys_removed=yes some_user +``` + +### Principal Roles + +The `principal-roles` command is used to create, discover, and manage principal roles within Polaris. Additionally, this command can identify principals or catalog roles associated with a principal role, and can be used to grant a principal role to a principal. + +`principal-roles` supports the following subcommands: + +1. create +2. delete +3. get +4. list +5. update +6. grant +7. revoke + +#### create + +The `create` subcommand is used to create a new principal role. + +``` +input: polaris principal-roles create --help +options: + create + Named arguments: + --property A key/value pair such as: tag=value. Multiple can be provided by specifying this option more than once + Positional arguments: + principal_role +``` + +##### Examples + +``` +polaris principal-roles create data_engineer + +polaris principal-roles create --property key=value data_analyst +``` + +#### delete + +The `delete` subcommand is used to delete a principal role. + +``` +input: polaris principal-roles delete --help +options: + delete + Positional arguments: + principal_role +``` + +##### Examples + +``` +polaris principal-roles delete data_engineer + +polaris principal-roles delete data_analyst +``` + +#### get + +The `get` subcommand retrieves details about a principal role. + +``` +input: polaris principal-roles get --help +options: + get + Positional arguments: + principal_role +``` + +##### Examples + +``` +polaris principal-roles get data_engineer + +polaris principal-roles get data_analyst +``` + +#### list + +The list subcommand is used to print out all principal roles or, alternatively, to list all principal roles associated with a given principal or with a given catalog role. + +``` +input: polaris principal-roles list --help +options: + list + Named arguments: + --catalog-role The name of a catalog role. If provided, show only principal roles assigned to this catalog role. + --principal The name of a principal. If provided, show only principal roles assigned to this principal. +``` + +##### Examples + +``` +polaris principal-roles list + +polaris principal-roles --principal d.knuth + +polaris principal-roles --catalog-role super_secret_data +``` + +#### update + +The `update` subcommand is used to update a principal role. Currently, this supports updating the properties tied to a principal role. + +``` +input: polaris principal-roles update --help +options: + update + Named arguments: + --property A key/value pair such as: tag=value. Multiple can be provided by specifying this option more than once + Positional arguments: + principal_role +``` + +##### Examples + +``` +polaris principal-roles update --property key=value2 data_engineer + +polaris principal-roles update data_analyst --property key=value3 +``` + +#### grant + +The `grant` subcommand is used to grant a principal role to a principal. + +``` +input: polaris principal-roles grant --help +options: + grant + Named arguments: + --principal A principal to grant this principal role to + Positional arguments: + principal_role +``` + +##### Examples + +``` +polaris principal-roles grant --principal d.knuth data_engineer + +polaris principal-roles grant data_scientist --principal a.ng +``` + +#### revoke + +The `revoke` subcommand is used to revoke a principal role from a principal. + +``` +input: polaris principal-roles revoke --help +options: + revoke + Named arguments: + --principal A principal to revoke this principal role from + Positional arguments: + principal_role +``` + +##### Examples + +``` +polaris principal-roles revoke --principal former.employee data_engineer + +polaris principal-roles revoke data_scientist --principal changed.role +``` + +### Catalog Roles + +The catalog-roles command is used to create, discover, and manage catalog roles within Polaris. Additionally, this command can be used to grant a catalog role to a principal role. + +`catalog-roles` supports the following subcommands: + +1. create +2. delete +3. get +4. list +5. update +6. grant +7. revoke + +#### create + +The `create` subcommand is used to create a new catalog role. + +``` +input: polaris catalog-roles create --help +options: + create + Named arguments: + --catalog The name of an existing catalog + --property A key/value pair such as: tag=value. Multiple can be provided by specifying this option more than once + Positional arguments: + catalog_role +``` + +##### Examples + +``` +polaris catalog-roles create --property key=value --catalog some_catalog sales_data + +polaris catalog-roles create --catalog other_catalog sales_data +``` + +#### delete + +The `delete` subcommand is used to delete a catalog role. + +``` +input: polaris catalog-roles delete --help +options: + delete + Named arguments: + --catalog The name of an existing catalog + Positional arguments: + catalog_role +``` + +##### Examples + +``` +polaris catalog-roles delete --catalog some_catalog sales_data + +polaris catalog-roles delete --catalog other_catalog sales_data +``` + +#### get + +The `get` subcommand retrieves details about a catalog role. + +``` +input: polaris catalog-roles get --help +options: + get + Named arguments: + --catalog The name of an existing catalog + Positional arguments: + catalog_role +``` + +##### Examples + +``` +polaris catalog-roles get --catalog some_catalog inventory_data + +polaris catalog-roles get --catalog other_catalog inventory_data +``` + +#### list + +The `list` subcommand is used to print all catalog roles. Alternatively, if a principal role is provided, only catalog roles associated with that principal are shown. + +``` +input: polaris catalog-roles list --help +options: + list + Named arguments: + --principal-role The name of a principal role + Positional arguments: + catalog +``` + +##### Examples + +``` +polaris catalog-roles list + +polaris catalog-roles list --principal-role data_engineer +``` + +#### update + +The `update` subcommand is used to update a catalog role. Currently, only updating properties associated with the catalog role is supported. + +``` +input: polaris catalog-roles update --help +options: + update + Named arguments: + --catalog The name of an existing catalog + --property A key/value pair such as: tag=value. Multiple can be provided by specifying this option more than once + Positional arguments: + catalog_role +``` + +##### Examples + +``` +polaris catalog-roles update --property contains_pii=true --catalog some_catalog sales_data + +polaris catalog-roles update sales_data --catalog some_catalog --property key=value +``` + +#### grant + +The `grant` subcommand is used to grant a catalog role to a principal role. + +``` +input: polaris catalog-roles grant --help +options: + grant + Named arguments: + --catalog The name of an existing catalog + --principal-role The name of a catalog role + Positional arguments: + catalog_role +``` + +##### Examples + +``` +polaris catalog-roles grant sensitive_data --catalog some_catalog --principal-role power_user + +polaris catalog-roles grant --catalog sales_data contains_cc_info_catalog_role --principal-role financial_analyst_role +``` + +#### revoke + +The `revoke` subcommand is used to revoke a catalog role from a principal role. + +``` +input: polaris catalog-roles revoke --help +options: + revoke + Named arguments: + --catalog The name of an existing catalog + --principal-role The name of a catalog role + Positional arguments: + catalog_role +``` + +##### Examples + +``` +polaris catalog-roles revoke sensitive_data --catalog some_catalog --principal-role power_user + +polaris catalog-roles revoke --catalog sales_data contains_cc_info_catalog_role --principal-role financial_analyst_role +``` + +### Namespaces + +The `namespaces` command is used to manage namespaces within Polaris. + +`namespaces` supports the following subcommands: + +1. create +2. delete +3. get +4. list + +#### create + +The `create` subcommand is used to create a new namespace. + +When creating a namespace with an explicit location, that location must reside within the parent catalog or namespace. + +``` +input: polaris namespaces create --help +options: + create + Named arguments: + --catalog The name of an existing catalog + --location If specified, the location at which to store the namespace and entities inside it + --property A key/value pair such as: tag=value. Multiple can be provided by specifying this option more than once + Positional arguments: + namespace +``` + +##### Examples + +``` +polaris namespaces create --catalog my_catalog outer + +polaris namespaces create --catalog my_catalog --location 's3://bucket/outer/inner_SUFFIX' outer.inner +``` + +#### delete + +The `delete` subcommand is used to delete a namespace. + +``` +input: polaris namespaces delete --help +options: + delete + Named arguments: + --catalog The name of an existing catalog + Positional arguments: + namespace +``` + +##### Examples + +``` +polaris namespaces delete outer_namespace.inner_namespace --catalog my_catalog + +polaris namespaces delete --catalog my_catalog outer_namespace +``` + +#### get + +The `get` subcommand retrieves details about a namespace. + +``` +input: polaris namespaces get --help +options: + get + Named arguments: + --catalog The name of an existing catalog + Positional arguments: + namespace +``` + +##### Examples + +``` +polaris namespaces get --catalog some_catalog a.b + +polaris namespaces get a.b.c --catalog some_catalog +``` + +#### list + +The `list` subcommand shows details about all namespaces directly within a catalog or, optionally, within some parent prefix in that catalog. + +``` +input: polaris namespaces list --help +options: + list + Named arguments: + --catalog The name of an existing catalog + --parent If specified, list namespaces inside this parent namespace +``` + +##### Examples + +``` +polaris namespaces list --catalog my_catalog + +polaris namespaces list --catalog my_catalog --parent a + +polaris namespaces list --catalog my_catalog --parent a.b +``` + +### Privileges + +The `privileges` command is used to grant various privileges to a catalog role, or to revoke those privileges. Privileges can be on the level of a catalog, a namespace, a table, or a view. For more information on privileges, please refer to the [docs](entities.mdrivilege). + +Note that when using the `privileges` command, the user specifies the relevant catalog and catalog role before selecting a subcommand. + +`privileges` supports the following subcommands: + +1. list +2. catalog +3. namespace +4. table +5. view + +Each of these subcommands, except `list`, supports the `grant` and `revoke` actions and requires an action to be specified. + +Note that each subcommand's `revoke` action always accepts the same options that the corresponding `grant` action does, but with the addition of the `cascade` option. `cascade` is used to revoke all other privileges that depend on the specified privilege. + +#### list + +The `list` subcommand shows details about all privileges for a catalog role. + +``` +input: polaris privileges list --help +options: + list + Named arguments: + --catalog The name of an existing catalog + --catalog-role The name of a catalog role +``` + +##### Examples + +``` +polaris privileges list --catalog my_catalog --catalog-role my_role + +polaris privileges my_role list --catalog-role my_other_role --catalog my_catalog +``` + +#### catalog + +The `catalog` subcommand manages privileges at the catalog level. `grant` is used to grant catalog privileges to the specified catalog role, and `revoke` is used to revoke them. + +``` +input: polaris privileges catalog --help +options: + catalog + grant + Named arguments: + --catalog The name of an existing catalog + --catalog-role The name of a catalog role + Positional arguments: + privilege + revoke + Named arguments: + --cascade When revoking privileges, additionally revoke privileges that depend on the specified privilege + --catalog The name of an existing catalog + --catalog-role The name of a catalog role + Positional arguments: + privilege +``` + +##### Examples + +``` +polaris privileges \ + catalog \ + grant \ + --catalog my_catalog \ + --catalog-role catalog_role \ + TABLE_CREATE + +polaris privileges \ + catalog \ + revoke \ + --catalog my_catalog \ + --catalog-role catalog_role \ + --cascade \ + TABLE_CREATE +``` + +#### namespace + +The `namespace` subcommand manages privileges at the namespace level. + +``` +input: polaris privileges namespace --help +options: + namespace + grant + Named arguments: + --namespace A period-delimited namespace + --catalog The name of an existing catalog + --catalog-role The name of a catalog role + Positional arguments: + privilege + revoke + Named arguments: + --namespace A period-delimited namespace + --cascade When revoking privileges, additionally revoke privileges that depend on the specified privilege + --catalog The name of an existing catalog + --catalog-role The name of a catalog role + Positional arguments: + privilege +``` + +##### Examples + +``` +polaris privileges \ + namespace \ + grant \ + --catalog my_catalog \ + --catalog-role catalog_role \ + --namespace a.b \ + TABLE_LIST + +polaris privileges \ + namespace \ + revoke \ + --catalog my_catalog \ + --catalog-role catalog_role \ + --namespace a.b \ + TABLE_LIST +``` + +#### table + +The `table` subcommand manages privileges at the table level. + +``` +input: polaris privileges table --help +options: + table + grant + Named arguments: + --namespace A period-delimited namespace + --table The name of a table + --catalog The name of an existing catalog + --catalog-role The name of a catalog role + Positional arguments: + privilege + revoke + Named arguments: + --namespace A period-delimited namespace + --table The name of a table + --cascade When revoking privileges, additionally revoke privileges that depend on the specified privilege + --catalog The name of an existing catalog + --catalog-role The name of a catalog role + Positional arguments: + privilege +``` + +##### Examples + +``` +polaris privileges \ + table \ + grant \ + --catalog my_catalog \ + --catalog-role catalog_role \ + --namespace a.b \ + --table t \ + TABLE_DROP + +polaris privileges \ + table \ + grant \ + --catalog my_catalog \ + --catalog-role catalog_role \ + --namespace a.b \ + --table t \ + --cascade \ + TABLE_DROP +``` + +#### view + +The `view` subcommand manages privileges at the view level. + +``` +input: polaris privileges view --help +options: + view + grant + Named arguments: + --namespace A period-delimited namespace + --view The name of a view + --catalog The name of an existing catalog + --catalog-role The name of a catalog role + Positional arguments: + privilege + revoke + Named arguments: + --namespace A period-delimited namespace + --view The name of a view + --cascade When revoking privileges, additionally revoke privileges that depend on the specified privilege + --catalog The name of an existing catalog + --catalog-role The name of a catalog role + Positional arguments: + privilege +``` + +##### Examples + +``` +polaris privileges \ + view \ + grant \ + --catalog my_catalog \ + --catalog-role catalog_role \ + --namespace a.b.c \ + --view v \ + VIEW_FULL_METADATA + +polaris privileges \ + view \ + grant \ + --catalog my_catalog \ + --catalog-role catalog_role \ + --namespace a.b.c \ + --view v \ + --cascade \ + VIEW_FULL_METADATA +``` + +## Examples + +This section outlines example code for a few common operations as well as for some more complex ones. + +For especially complex operations, you may wish to instead directly use the Python API. + +### Creating a principal and a catalog + +``` +polaris principals create my_user + +polaris catalogs create \ + --type internal \ + --storage-type s3 \ + --default-base-location s3://iceberg-bucket/polaris-base \ + --role-arn arn:aws:iam::111122223333:role/ExampleCorpRole \ + --allowed-location s3://iceberg-bucket/polaris-alt-location-1 \ + --allowed-location s3://iceberg-bucket/polaris-alt-location-2 \ + my_catalog +``` + +### Granting a principal the ability to manage the content of a catalog + +``` +polaris principal-roles create power_user +polaris principal-roles grant --principal my_user power_user + +polaris catalog-roles create --catalog my_catalog my_catalog_role +polaris catalog-roles grant \ + --catalog my_catalog \ + --principal-role power_user \ + my_catalog_role + +polaris privileges \ + catalog \ + --catalog my_catalog \ + --catalog-role my_catalog_role \ + grant \ + CATALOG_MANAGE_CONTENT +``` + +### Identifying the tables a given principal has been granted explicit access to read + +_Note that some other privileges, such as `CATALOG_MANAGE_CONTENT`, subsume `TABLE_READ_DATA` and would not be discovered here._ + +``` +principal_roles=$(polaris principal-roles list --principal my_principal) +for principal_role in ${principal_roles}; do + catalog_roles=$(polaris catalog-roles --list --principal-role "${principal_role}") + for catalog_role in ${catalog_roles}; do + grants=$(polaris privileges list --catalog-role "${catalog_role}" --catalog "${catalog}") + for grant in $(echo "${grants}" | jq -c '.[] | select(.privilege == "TABLE_READ_DATA")'); do + echo "${grant}" + fi + done + done +done +``` + + diff --git a/site/content/in-dev/unreleased/documentation/configuring-polaris-for-production.md b/site/content/in-dev/unreleased/documentation/configuring-polaris-for-production.md new file mode 100644 index 000000000..86359d65b --- /dev/null +++ b/site/content/in-dev/unreleased/documentation/configuring-polaris-for-production.md @@ -0,0 +1,106 @@ +--- +# +# 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. +# +title: Configuring Apache Polaris (Incubating) for Production +linkTitle: Deploying In Production +type: docs +weight: 500 +--- + + +The default `polaris-server.yml` configuration is intended for develoment and testing. When deploying Polaris in production, there are several best practices to keep in mind. + +## Security + +### Configurations + +Notable configuration used to secure a Polaris deployment are outlined below. + +#### oauth2 + +> [!WARNING] +> Ensure that the `tokenBroker` setting reflects the token broker specified in `authenticator` below. + +* Configure [OAuth](https://oauth.net/2/) with this setting. Remove the `TestInlineBearerTokenPolarisAuthenticator` option and uncomment the `DefaultPolarisAuthenticator` authenticator option beneath it. +* Then, configure the token broker. You can configure the token broker to use either [asymmetric](https://github.com/apache/polaris/blob/b482617bf8cc508b37dbedf3ebc81a9408160a5e/polaris-service/src/main/java/io/polaris/service/auth/JWTRSAKeyPair.java#L24) or [symmetric](https://github.com/apache/polaris/blob/b482617bf8cc508b37dbedf3ebc81a9408160a5e/polaris-service/src/main/java/io/polaris/service/auth/JWTSymmetricKeyBroker.java#L23) keys. + +#### authenticator.tokenBroker + +> [!WARNING] +> Ensure that the `tokenBroker` setting reflects the token broker specified in `oauth2` above. + +#### callContextResolver & realmContextResolver +* Use these configurations to specify a service that can resolve a realm from bearer tokens. +* The service(s) used here must implement the relevant interfaces (i.e. [CallContextResolver](https://github.com/apache/polaris/blob/8290019c10290a600e40b35ddb1e2f54bf99e120/polaris-service/src/main/java/io/polaris/service/context/CallContextResolver.java#L27) and [RealmContextResolver](https://github.com/apache/polaris/blob/7ce86f10a68a3b56aed766235c88d6027c0de038/polaris-service/src/main/java/io/polaris/service/context/RealmContextResolver.java)). + +## Metastore Management + +> [!IMPORTANT] +> The default `in-memory` implementation for `metastoreManager` is meant for testing and not suitable for production usage. Instead, consider an implementation such as `eclipse-link` which allows you to store metadata in a remote database. + +A Metastore Manger should be configured with an implementation that durably persists Polaris entities. Use the configuration `metaStoreManager` to configure a [MetastoreManager](https://github.com/apache/polaris/blob/627dc602eb15a3258dcc32babf8def34cf6de0e9/polaris-core/src/main/java/io/polaris/core/persistence/PolarisMetaStoreManager.java#L47) implementation where Polaris entities will be persisted. + +Be sure to secure your metastore backend since it will be storing credentials and catalog metadata. + +### Configuring EclipseLink + +To use [EclipseLink](https://eclipse.dev/eclipselink/) for metastore management, specify the configuration `metaStoreManager.conf-file` to point to an [EclipseLink `persistence.xml` file](https://eclipse.dev/eclipselink/documentation/2.5/solutions/testingjpa002.htm). This file, local to the Polaris service, will contain information on what database to use for metastore management and how to connect to it. + +### Bootstrapping + +Before using Polaris when using a metastore manager other than `in-memory`, you must **bootstrap** the metastore manager. This is a manual operation that must be performed **only once** in order to prepare the metastore manager to integrate with Polaris. When the metastore manager is bootstrapped, any existing Polaris entities in the metastore manager may be **purged**. + +To bootstrap Polaris, run: + +```bash +java -jar /path/to/jar/polaris-service-all.jar bootstrap polaris-server.yml +``` + +Afterwards, Polaris can be launched normally: + +```bash +java -jar /path/to/jar/polaris-service-all.jar server polaris-server.yml +``` + +## Other Configurations + +When deploying Polaris in production, consider adjusting the following configurations: + +#### featureConfiguration.SUPPORTED_CATALOG_STORAGE_TYPES + - By default Polaris catalogs are allowed to be located in local filesystem with the `FILE` storage type. This should be disabled for production systems. + - Use this configuration to additionally disable any other storage types that will not be in use. + + diff --git a/site/content/in-dev/unreleased/documentation/entities.md b/site/content/in-dev/unreleased/documentation/entities.md new file mode 100644 index 000000000..e03179b47 --- /dev/null +++ b/site/content/in-dev/unreleased/documentation/entities.md @@ -0,0 +1,107 @@ +--- +# +# 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. +# +Title: Entities +type: docs +weight: 300 +--- + + +This page documents various entities that can be managed in Apache Polaris (Incubating). + +## Catalog + +A catalog is a top-level entity in Polaris that may contain other entities like [namespaces](#namespace) and [tables](#table). These map directly to [Apache Iceberg catalogs](https://iceberg.apache.org/concepts/catalog/). + +For information on managing catalogs with the REST API or for more information on what data can be associated with a catalog, see [the API docs](../regtests/client/python/docs/CreateCatalogRequest.md). + +### Storage Type + +All catalogs in Polaris are associated with a _storage type_. Valid Storage Types are `S3`, `Azure`, and `GCS`. The `FILE` type is also additionally available for testing. Each of these types relates to a different storage provider where data within the catalog may reside. Depending on the storage type, various other configurations may be set for a catalog including credentials to be used when accessing data inside the catalog. + +For details on how to use Storage Types in the REST API, see [the API docs](../regtests/client/python/docs/StorageConfigInfo.md). + +## Namespace + +A namespace is a logical entity that resides within a [catalog](#catalog) and can contain other entities such as [tables](#table) or [views](#view). Some other systems may refer to namespaces as _schemas_ or _databases_. + +In Polaris, namespaces can be nested. For example, `a.b.c.d.e.f.g` is a valid namespace. `b` is said to reside within `a`, and so on. + +For information on managing namespaces with the REST API or for more information on what data can be associated with a namespace, see [the API docs](../regtests/client/python/docs/CreateNamespaceRequest.md). + + +## Table + +Polaris tables are entities that map to [Apache Iceberg tables](https://iceberg.apache.org/docs/nightly/configuration/). + +For information on managing tables with the REST API or for more information on what data can be associated with a table, see [the API docs](../regtests/client/python/docs/CreateTableRequest.md). + +## View + +Polaris views are entities that map to [Apache Iceberg views](https://iceberg.apache.org/view-spec/). + +For information on managing views with the REST API or for more information on what data can be associated with a view, see [the API docs](../regtests/client/python/docs/CreateViewRequest.md). + +## Principal + +Polaris principals are unique identities that can be used to represent users or services. Each principal may have one or more [principal roles](#principal-role) assigned to it for the purpose of accessing catalogs and the entities within them. + +For information on managing principals with the REST API or for more information on what data can be associated with a principal, see [the API docs](../regtests/client/python/docs/CreatePrincipalRequest.md). + +## Principal Role + +Polaris principal roles are labels that may be granted to [principals](#principal). Each principal may have one or more principal roles, and the same principal role may be granted to multiple principals. Principal roles may be assigned based on the persona or responsibilities of a given principal, or on how that principal will need to access different entities within Polaris. + +For information on managing principal roles with the REST API or for more information on what data can be associated with a principal role, see [the API docs](../regtests/client/python/docs/CreatePrincipalRoleRequest.md). + + +## Catalog Role + +Polaris catalog roles are labels that may be granted to [catalogs](#catalog). Each catalog may have one or more catalog roles, and the same catalog role may be granted to multiple catalogs. Catalog roles may be assigned based on the nature of data that will reside in a catalog, or by the groups of users and services that might need to access that data. + +Each catalog role may have multiple [privileges](#privilege) granted to it, and each catalog role can be granted to one or more [principal roles](#principal-role). This is the mechanism by which principals are granted access to entities inside a catalog such as namespaces and tables. + +## Privilege + +Polaris privileges are granted to [catalog roles](#catalog-role) in order to grant principals with a given principal role some degree of access to catalogs with a given catalog role. When a privilege is granted to a catalog role, any principal roles granted that catalog role receive the privilege. In turn, any principals who are granted that principal role receive it. + +A privilege can be scoped to any entity inside a catalog, including the catalog itself. + +For a list of supported privileges for each privilege class, see the API docs: +* [Table Privileges](../regtests/client/python/docs/TablePrivilege.md) +* [View Privileges](../regtests/client/python/docs/ViewPrivilege.md) +* [Namespace Privileges](../regtests/client/python/docs/NamespacePrivilege.md) +* [Catalog Privileges](../regtests/client/python/docs/CatalogPrivilege.md) diff --git a/site/content/in-dev/unreleased/quickstart.md b/site/content/in-dev/unreleased/quickstart.md new file mode 100644 index 000000000..c0ab5c479 --- /dev/null +++ b/site/content/in-dev/unreleased/quickstart.md @@ -0,0 +1,350 @@ +--- +# +# 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. +# +Title: Quick Start +type: docs +weight: 100 +--- + + +This guide serves as a introduction to several key entities that can be managed with Apache Polaris (Incubating), describes how to build and deploy Polaris locally, and finally includes examples of how to use Polaris with Apache Spark™. + +## Prerequisites + +This guide covers building Polaris, deploying it locally or via [Docker](https://www.docker.com/), and interacting with it using the command-line interface and [Apache Spark](https://spark.apache.org/). Before proceeding with Polaris, be sure to satisfy the relevant prerequisites listed here. + +### Building and Deploying Polaris + +To get the latest Polaris code, you'll need to clone the repository using [git](https://git-scm.com/). You can install git using [homebrew](https://brew.sh/): + +```shell +brew install git +``` + +Then, use git to clone the Polaris repo: + +```shell +cd ~ +git clone https://github.com/apache/polaris.git +``` + +#### With Docker + +If you plan to deploy Polaris inside [Docker](https://www.docker.com/), you'll need to install docker itself. For example, this can be done using [homebrew](https://brew.sh/): + +```shell +brew install --cask docker +``` + +Once installed, make sure Docker is running. + +#### From Source + +If you plan to build Polaris from source yourself, you will need to satisfy a few prerequisites first. + +Polaris is built using [gradle](https://gradle.org/) and is compatible with Java 21. We recommend the use of [jenv](https://www.jenv.be/) to manage multiple Java versions. For example, to install Java 21 via [homebrew](https://brew.sh/) and configure it with jenv: + +```shell +cd ~/polaris +brew install openjdk@21 jenv +jenv add $(brew --prefix openjdk@21) +jenv local 21 +``` + +### Connecting to Polaris + +Polaris is compatible with any [Apache Iceberg](https://iceberg.apache.org/) client that supports the REST API. Depending on the client you plan to use, refer to the prerequisites below. + +#### With Spark + +If you want to connect to Polaris with [Apache Spark](https://spark.apache.org/), you'll need to start by cloning Spark. As [above](#building-and-deploying-polaris), make sure [git](https://git-scm.com/) is installed first. You can install it with [homebrew](https://brew.sh/): + +```shell +brew install git +``` + +Then, clone Spark and check out a versioned branch. This guide uses [Spark 3.5](https://spark.apache.org/releases/spark-release-3-5-0.html). + +```shell +cd ~ +git clone https://github.com/apache/spark.git +cd ~/spark +git checkout branch-3.5 +``` + +## Deploying Polaris + +Polaris can be deployed via a lightweight docker image or as a standalone process. Before starting, be sure that you've satisfied the relevant [prerequisites](#building-and-deploying-polaris) detailed above. + +### Docker Image + +To start using Polaris in Docker, launch Polaris while Docker is running: + +```shell +cd ~/polaris +docker compose -f docker-compose.yml up --build +``` + +Once the `polaris-polaris` container is up, you can continue to [Defining a Catalog](#defining-a-catalog). + +### Building Polaris + +Run Polaris locally with: + +```shell +cd ~/polaris +./gradlew runApp +``` + +You should see output for some time as Polaris builds and starts up. Eventually, you won’t see any more logs and should see messages that resemble the following: + +``` +INFO [...] [main] [] o.e.j.s.handler.ContextHandler: Started i.d.j.MutableServletContextHandler@... +INFO [...] [main] [] o.e.j.server.AbstractConnector: Started application@... +INFO [...] [main] [] o.e.j.server.AbstractConnector: Started admin@... +INFO [...] [main] [] o.eclipse.jetty.server.Server: Started Server@... +``` + +At this point, Polaris is running. + +## Bootstrapping Polaris + +For this tutorial, we'll launch an instance of Polaris that stores entities only in-memory. This means that any entities that you define will be destroyed when Polaris is shut down. It also means that Polaris will automatically bootstrap itself with root credentials. For more information on how to configure Polaris for production usage, see the [docs](documentation/configuring-polaris-for-production.md). + +When Polaris is launched using in-memory mode the root principal credentials can be found in stdout on initial startup. For example: + +``` +realm: default-realm root principal credentials: : +``` + +Be sure to note of these credentials as we'll be using them below. You can also set these credentials as environment variables for use with the Polaris CLI: + +```shell +export CLIENT_ID= +export CLIENT_SECRET= +``` + +## Defining a Catalog + +In Polaris, the [catalog](documentation/entities.md#catalog) is the top-level entity that objects like [tables](documentation/entities.md#table) and [views](documentation/entities.md#view) are organized under. With a Polaris service running, you can create a catalog like so: + +```shell +cd ~/polaris + +./polaris \ + --client-id ${CLIENT_ID} \ + --client-secret ${CLIENT_SECRET} \ + catalogs \ + create \ + --storage-type s3 \ + --default-base-location ${DEFAULT_BASE_LOCATION} \ + --role-arn ${ROLE_ARN} \ + quickstart_catalog +``` + +This will create a new catalog called **quickstart_catalog**. + +The `DEFAULT_BASE_LOCATION` you provide will be the default location that objects in this catalog should be stored in, and the `ROLE_ARN` you provide should be a [Role ARN](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference-arns.html) with access to read and write data in that location. These credentials will be provided to engines reading data from the catalog once they have authenticated with Polaris using credentials that have access to those resources. + +If you’re using a storage type other than S3, such as Azure, you’ll provide a different type of credential than a Role ARN. For more details on supported storage types, see the [docs](documentation/entities.md#storage-type). + +Additionally, if Polaris is running somewhere other than `localhost:8181`, you can specify the correct hostname and port by providing `--host` and `--port` flags. For the full set of options supported by the CLI, please refer to the [docs](documentation/command-line-interface.md). + + +### Creating a Principal and Assigning it Privileges + +With a catalog created, we can create a [principal](documentation/entities.md#principal) that has access to manage that catalog. For details on how to configure the Polaris CLI, see [the section above](#defining-a-catalog) or refer to the [docs](documentation/command-line-interface.md). + +```shell +./polaris \ + --client-id ${CLIENT_ID} \ + --client-secret ${CLIENT_SECRET} \ + principals \ + create \ + quickstart_user + +./polaris \ + --client-id ${CLIENT_ID} \ + --client-secret ${CLIENT_SECRET} \ + principal-roles \ + create \ + quickstart_user_role + +./polaris \ + --client-id ${CLIENT_ID} \ + --client-secret ${CLIENT_SECRET} \ + catalog-roles \ + create \ + --catalog quickstart_catalog \ + quickstart_catalog_role +``` + +Be sure to provide the necessary credentials, hostname, and port as before. + +When the `principals create` command completes successfully, it will return the credentials for this new principal. Be sure to note these down for later. For example: + +``` +./polaris ... principals create example +{"clientId": "XXXX", "clientSecret": "YYYY"} +``` + +Now, we grant the principal the [principal role](documentation/entities.md#principal-role) we created, and grant the [catalog role](documentation/entities.md#catalog-role) the principal role we created. For more information on these entities, please refer to the linked documentation. + +```shell +./polaris \ + --client-id ${CLIENT_ID} \ + --client-secret ${CLIENT_SECRET} \ + principal-roles \ + grant \ + --principal quickstart_user \ + quickstart_user_role + +./polaris \ + --client-id ${CLIENT_ID} \ + --client-secret ${CLIENT_SECRET} \ + catalog-roles \ + grant \ + --catalog quickstart_catalog \ + --principal-role quickstart_user_role \ + quickstart_catalog_role +``` + +Now, we’ve linked our principal to the catalog via roles like so: + +![Principal to Catalog](/img/quickstart/privilege-illustration-1.png "Principal to Catalog") + +In order to give this principal the ability to interact with the catalog, we must assign some [privileges](documentation/entities.md#privilege). For the time being, we will give this principal the ability to fully manage content in our new catalog. We can do this with the CLI like so: + +```shell +./polaris \ + --client-id ${CLIENT_ID} \ + --client-secret ${CLIENT_SECRET} \ + privileges \ + catalog \ + grant \ + --catalog quickstart_catalog \ + --catalog-role quickstart_catalog_role \ + CATALOG_MANAGE_CONTENT +``` + +This grants the [catalog privileges](documentation/entities.md#privilege) `CATALOG_MANAGE_CONTENT` to our catalog role, linking everything together like so: + +![Principal to Catalog with Catalog Role](/img/quickstart/privilege-illustration-2.png "Principal to Catalog with Catalog Role") + +`CATALOG_MANAGE_CONTENT` has create/list/read/write privileges on all entities within the catalog. The same privilege could be granted to a namespace, in which case the principal could create/list/read/write any entity under that namespace. + +## Using Iceberg & Polaris + +At this point, we’ve created a principal and granted it the ability to manage a catalog. We can now use an external engine to assume that principal, access our catalog, and store data in that catalog using [Apache Iceberg](https://iceberg.apache.org/). + +### Connecting with Spark + +To use a Polaris-managed catalog in [Apache Spark](https://spark.apache.org/), we can configure Spark to use the Iceberg catalog REST API. + +This guide uses [Apache Spark 3.5](https://spark.apache.org/releases/spark-release-3-5-0.html), but be sure to find [the appropriate iceberg-spark package for your Spark version](https://mvnrepository.com/artifact/org.apache.iceberg/iceberg-spark). From a local Spark clone on the `branch-3.5` branch we can run the following: + +_Note: the credentials provided here are those for our principal, not the root credentials._ + +```shell +bin/spark-shell \ +--packages org.apache.iceberg:iceberg-spark-runtime-3.5_2.12:1.5.2,org.apache.hadoop:hadoop-aws:3.4.0 \ +--conf spark.sql.extensions=org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions \ +--conf spark.sql.catalog.quickstart_catalog.warehouse=quickstart_catalog \ +--conf spark.sql.catalog.quickstart_catalog.header.X-Iceberg-Access-Delegation=vended-credentials \ +--conf spark.sql.catalog.quickstart_catalog=org.apache.iceberg.spark.SparkCatalog \ +--conf spark.sql.catalog.quickstart_catalog.catalog-impl=org.apache.iceberg.rest.RESTCatalog \ +--conf spark.sql.catalog.quickstart_catalog.uri=http://localhost:8181/api/catalog \ +--conf spark.sql.catalog.quickstart_catalog.credential='XXXX:YYYY' \ +--conf spark.sql.catalog.quickstart_catalog.scope='PRINCIPAL_ROLE:ALL' \ +--conf spark.sql.catalog.quickstart_catalog.token-refresh-enabled=true +``` + + +Replace `XXXX` and `YYYY` with the client ID and client secret generated when you created the `quickstart_user` principal. + +Similar to the CLI commands above, this configures Spark to use the Polaris running at `localhost:8181`. If your Polaris server is running elsewhere, but sure to update the configuration appropriately. + +Finally, note that we include the `hadoop-aws` package here. If your table is using a different filesystem, be sure to include the appropriate dependency. + +Once the Spark session starts, we can create a namespace and table within the catalog: + +``` +spark.sql("USE quickstart_catalog") +spark.sql("CREATE NAMESPACE IF NOT EXISTS quickstart_namespace") +spark.sql("CREATE NAMESPACE IF NOT EXISTS quickstart_namespace.schema") +spark.sql("USE NAMESPACE quickstart_namespace.schema") +spark.sql(""" + CREATE TABLE IF NOT EXISTS quickstart_table ( + id BIGINT, data STRING + ) +USING ICEBERG +""") +``` + +We can now use this table like any other: + +``` +spark.sql("INSERT INTO quickstart_table VALUES (1, 'some data')") +spark.sql("SELECT * FROM quickstart_table").show(false) +. . . ++---+---------+ +|id |data | ++---+---------+ +|1 |some data| ++---+---------+ +``` + +If at any time access is revoked... + +```shell +./polaris \ + --client-id ${CLIENT_ID} \ + --client-secret ${CLIENT_SECRET} \ + privileges \ + catalog \ + revoke \ + --catalog quickstart_catalog \ + --catalog-role quickstart_catalog_role \ + CATALOG_MANAGE_CONTENT +``` + +Spark will lose access to the table: + +``` +spark.sql("SELECT * FROM quickstart_table").show(false) + +org.apache.iceberg.exceptions.ForbiddenException: Forbidden: Principal 'quickstart_user' with activated PrincipalRoles '[]' and activated ids '[6, 7]' is not authorized for op LOAD_TABLE_WITH_READ_DELEGATION +``` diff --git a/site/docker/Dockerfile b/site/docker/Dockerfile new file mode 100644 index 000000000..0a79e9949 --- /dev/null +++ b/site/docker/Dockerfile @@ -0,0 +1,32 @@ +# +# 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. +# + +FROM ubuntu:24.10 AS hugo + +RUN apt-get update +RUN apt-get install --yes golang hugo asciidoctor curl +RUN apt-get clean + +RUN mkdir /polaris + +COPY _run_in_docker.sh /hugo/run + +EXPOSE 1313 + +ENTRYPOINT ["/hugo/run"] diff --git a/site/docker/_run_in_docker.sh b/site/docker/_run_in_docker.sh new file mode 100755 index 000000000..3e9aef7a7 --- /dev/null +++ b/site/docker/_run_in_docker.sh @@ -0,0 +1,37 @@ +#!/usr/bin/env bash +# +# 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. +# + +# THIS SCRIPT IS ONLY INTENDED TO BE USED INSIDE THE HUGO DOCKER CONTAINER ! + +set -e + +cd /polaris + +exec hugo serve \ + --buildDrafts \ + --source /polaris/site \ + --cacheDir /hugo/cache \ + --noBuildLock \ + --renderToMemory \ + --cleanDestinationDir \ + --printPathWarnings \ + --printMemoryUsage \ + --printI18nWarnings \ + --bind 0.0.0.0 diff --git a/site/go.mod b/site/go.mod new file mode 100644 index 000000000..b3fd51372 --- /dev/null +++ b/site/go.mod @@ -0,0 +1,26 @@ +// +// 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. +// + +module github.com/apache/polaris + +go 1.22.2 + +require ( + github.com/google/docsy v0.10.0 // indirect +) diff --git a/site/go.sum b/site/go.sum new file mode 100644 index 000000000..78bc9349c --- /dev/null +++ b/site/go.sum @@ -0,0 +1,4 @@ +github.com/FortAwesome/Font-Awesome v0.0.0-20240402185447-c0f460dca7f7/go.mod h1:IUgezN/MFpCDIlFezw3L8j83oeiIuYoj28Miwr/KUYo= +github.com/google/docsy v0.10.0 h1:6tMDacPwAyRWNCfvsn/9qGOZDQ8b0aRzjRZvnZPY5dg= +github.com/google/docsy v0.10.0/go.mod h1:c0nIAqmRTOuJ01F85U/wJPQtc3Zj9N58Kea9bOT2AJc= +github.com/twbs/bootstrap v5.3.3+incompatible/go.mod h1:fZTSrkpSf0/HkL0IIJzvVspTt1r9zuf7XlZau8kpcY0= diff --git a/site/hugo.yaml b/site/hugo.yaml new file mode 100644 index 000000000..2a6da0370 --- /dev/null +++ b/site/hugo.yaml @@ -0,0 +1,241 @@ +# +# 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. +# + +baseURL: 'https://polaris.apache.org/' +languageCode: 'en-us' +title: 'Apache Polaris' +sectionPagesMenu: 'main' +enableRobotsTXT: true + +permalinks: + blog: "/:section/:year/:month/:day/:slug/" + +params: + author.name: 'Apache Polaris contributors' + offlineSearch: true + github_repo: https://github.com/apache/polaris + github_project_repo: https://github.com/apache/polaris + github_branch: main + github_subdir: site + privacy_policy: https://privacy.apache.org/policies/privacy-policy-public.html + + links: + # End user relevant links. These will show up on left side of footer and in the community page if you have one. + user: + - name: Zulip + url: https://polaris-catalog.zulipchat.com/ + icon: fa-regular fa-comment-dots + desc: Chat with other project developers + - name: Community Meetings + url: /community/meetings/ + icon: fa-brands fa-square-youtube + desc: Upcoming, live and recorded Community Meetings + developer: + - name: Dev mailing list + url: https://lists.apache.org/list.html?dev@polaris.apache.org + icon: fa fa-envelope + desc: Discussion and help from your fellow users + - name: GitHub + url: https://github.com/apache/polaris + icon: fab fa-github + desc: Development takes place here! + + # Not using Docsy's mechanism to show a "Releases" menu, because we want to differentiate between "active" and + # "EOL" releases and only show the "active" ones in the top navbar - and have the `Releases` menu not appear + # at the very right in the navbar. + active_releases: + # Mention all active releases here, in semver descending order + - "0.2.2" + - "0.2.1" + - "0.2.0" + - "0.1.1" + - "0.1.0" + + ui: + ul_show: 1 + sidebar_menu_compact: true + sidebar_menu_foldable: true + sidebar_cache_limit: 1000 + # Dark doesn't look great for example with the `redoc` shortcode :( + #showLightDarkModeMenu: true + sidebar_search_disable: true + + plantuml: + enable: true + markmap: + enable: true + +imaging: + resampleFilter: "CatmullRom" + quality: 75 + anchor: "smart" + +menu: + main: + - name: "Docs & Releases" + identifier: "releases" + weight: 800 + params: + orderby: weight.desc + - name: "All Releases" + identifier: "all-releases-page" + url: "/releases/" + parent: "releases" + - name: "In Development" + url: "/in-dev/unreleased/" + parent: "releases" + + - name: "Community" + identifier: "community" + weight: 300 + - name: "Community Page" + parent: "community" + url: "/community/" + weight: 10 + - name: "Meetings" + parent: "community" + url: "/community/meetings" + weight: 20 + - name: "Proposals" + parent: "community" + url: "/community/proposals" + weight: 30 + - name: "Code Of Conduct" + parent: "community" + url: "/community/code-of-conduct" + weight: 40 + - name: "Chat Bylaws" + parent: "community" + url: "/community/chat-bylaws" + weight: 50 + - name: "Contributing Guidelines" + parent: "community" + url: "/community/contributing-guidelines" + weight: 60 + + - name: "ASF" + pre: "" + identifier: "asf" + weight: 900 + params: + rel: "external" + external: true + - name: "Foundation" + parent: "asf" + url: "https://www.apache.org/" + weight: 41 + params: + rel: "external" + external: true + - name: "License" + parent: "asf" + url: "https://www.apache.org/licenses/" + weight: 42 + params: + rel: "external" + external: true + - name: "Events" + parent: "asf" + url: "https://www.apache.org/events/current-event.html" + weight: 43 + params: + rel: "external" + external: true + - name: "Privacy" + parent: "asf" + url: "https://privacy.apache.org/policies/privacy-policy-public.html" + weight: 44 + params: + rel: "external" + external: true + - name: "Security" + parent: "asf" + url: "https://github.com/apache/polaris/blob/main/SECURITY.md" + weight: 45 + params: + rel: "external" + external: true + - name: "Sponsorship" + parent: "asf" + url: "https://www.apache.org/foundation/sponsorship.html" + weight: 46 + params: + rel: "external" + external: true + - name: "Thanks" + parent: "asf" + url: "https://www.apache.org/foundation/thanks.html" + weight: 47 + params: + rel: "external" + external: true + +module: + hugoVersion: + extended: true + # The Hugo versions (as of 2024/09/04): + # in latest Ubuntu 24.04: 0.123.7 + # in brew: 0.134.0 + min: 0.123.7 + imports: + - path: github.com/google/docsy + # Pin to this release, newer releases _might_ break the customized layouts + version: v0.10.0 + +outputs: + section: + - HTML + - RSS + # Print support disabled until the `releases` layout supports it + #- print + +markup: + highlight: + anchorLineNos: false + codeFences: true + guessSyntax: false + hl_Lines: "" + hl_inline: false + lineAnchors: '' + lineNoStart: 1 + lineNos: false + lineNumbersInTable: true + noClasses: true + noHl: false + style: 'monokai' + tabWidth: 4 + +security: + exec: + # Add `asciidoctor` as an allowed executable + allow: [ '^(dart-)?sass(-embedded)?$', '^go$', '^npx$', '^postcss$', '^asciidoctor$' ] + +privacy: + googleAnalytics: + respectDoNotTrack: true + instagram: + simple: true + twitter: + enableDNT: false + simple: true + vimeo: + enableDNT: true + simple: true + youtube: + privacyEnhanced: true diff --git a/site/layouts/blog/baseof.html b/site/layouts/blog/baseof.html new file mode 100644 index 000000000..aba07493f --- /dev/null +++ b/site/layouts/blog/baseof.html @@ -0,0 +1,50 @@ + + + + {{ partial "head.html" . }} + + +
+ {{ partial "navbar.html" . }} +
+
+
+
+ +
+ {{ with .CurrentSection.OutputFormats.Get "rss" -}} + + + + {{ end -}} + {{ block "main" . }}{{ end }} +
+
+
+ {{ partial "footer.html" . }} +
+ {{ partial "scripts.html" . }} + + \ No newline at end of file diff --git a/site/layouts/community/list.html b/site/layouts/community/list.html new file mode 100644 index 000000000..ab83b54eb --- /dev/null +++ b/site/layouts/community/list.html @@ -0,0 +1,41 @@ +{{/* + 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 "main" -}} + +
+
+
+
+ +

{{ T "community_join" . }}

+

{{ T "community_introduce" . }}

+ +
+
+
+ +{{ with .Content -}} +
+ {{ . }} +
+{{- end -}} + +{{ end }} \ No newline at end of file diff --git a/site/layouts/docs/baseof.html b/site/layouts/docs/baseof.html new file mode 100644 index 000000000..73d37f1f5 --- /dev/null +++ b/site/layouts/docs/baseof.html @@ -0,0 +1,48 @@ + + + + {{ partial "head.html" . }} + + +
+ {{ partial "navbar.html" . }} +
+
+
+
+ + {{/* No right sidebar */}} +
+ {{ partial "version-banner.html" . }} + {{ if not .Site.Params.ui.breadcrumb_disable }}{{ partial "breadcrumb.html" . }}{{ end }} + {{ block "main" . }}{{ end }} +
+
+
+ {{ partial "footer.html" . }} +
+ {{ partial "scripts.html" . }} + + \ No newline at end of file diff --git a/site/layouts/home/baseof.html b/site/layouts/home/baseof.html new file mode 100644 index 000000000..e3a74bf58 --- /dev/null +++ b/site/layouts/home/baseof.html @@ -0,0 +1,39 @@ + + + + {{ partial "head.html" . }} + + +
+ {{ partial "navbar.html" . }} +
+ +
+
+ {{ block "main" . }}{{ end }} +
+ {{ partial "footer.html" . }} +
+ {{ partial "scripts.html" . }} + + \ No newline at end of file diff --git a/site/layouts/home/list.html b/site/layouts/home/list.html new file mode 100644 index 000000000..12a0be9c8 --- /dev/null +++ b/site/layouts/home/list.html @@ -0,0 +1,23 @@ +{{/* + 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 "main" -}} +
+ {{ .Content }} +
+{{ end }} \ No newline at end of file diff --git a/site/layouts/partials/community_links.html b/site/layouts/partials/community_links.html new file mode 100644 index 000000000..89dc764d0 --- /dev/null +++ b/site/layouts/partials/community_links.html @@ -0,0 +1,52 @@ +{{/* + 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. +*/}} +{{ $links := .Site.Params.links -}} +{{ $contribUrl := .Params.contributingUrl | default "docs/contribution-guidelines" -}} + +
+
+

{{ T "community_learn" }}

+

{{ T "community_using" . }}

+ {{ with index $links "user" -}} + {{ template "community-links-list" . -}} + {{ end }} +
+
+

{{ T "community_develop" }}

+

{{ T "community_contribute" . }}

+ {{ with index $links "developer" -}} + {{ template "community-links-list" . -}} + {{ end }} +

+ {{ T "community_how_to" . }} + {{ T "community_guideline" }}. +

+
+
+ +{{ define "community-links-list" -}} +
    + {{ range . -}} +
  • + {{ .name }}: + {{ .desc }} +
    • + {{ end }} +
+{{- end }} \ No newline at end of file diff --git a/site/layouts/partials/navbar.html b/site/layouts/partials/navbar.html new file mode 100644 index 000000000..433436b58 --- /dev/null +++ b/site/layouts/partials/navbar.html @@ -0,0 +1,122 @@ +{{/* +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. +*/}} +{{ $cover := and + (.HasShortcode "blocks/cover") + (not .Site.Params.ui.navbar_translucent_over_cover_disable) +-}} +{{ $baseURL := urls.Parse $.Site.Params.Baseurl -}} + + \ No newline at end of file diff --git a/site/layouts/partials/padZeroPrefix.html b/site/layouts/partials/padZeroPrefix.html new file mode 100644 index 000000000..2ef9be6f0 --- /dev/null +++ b/site/layouts/partials/padZeroPrefix.html @@ -0,0 +1,22 @@ +{{/* +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. +*/}} +{{- $padSize := 6 }} +{{- $paddedString := replaceRE "(\\d+)" (print (strings.Repeat (sub $padSize 1) "0") "$1") . }} +{{- $trimmedString := replaceRE (print "0+(\\d{" $padSize "})") "$1" $paddedString }} +{{- return $trimmedString }} \ No newline at end of file diff --git a/site/layouts/partials/releasePages.html b/site/layouts/partials/releasePages.html new file mode 100644 index 000000000..cef090859 --- /dev/null +++ b/site/layouts/partials/releasePages.html @@ -0,0 +1,45 @@ +{{/* +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. +*/}} +{{ $s := .site -}} + +{{ $releasesRootBy := $s.Pages.ByParam "all_releases_root" -}} +{{ $activeReleasePages := slice -}} +{{ $eolReleasePages := slice -}} + +{{ with $releasesRootBy -}} + {{ $releasesRootPage := index . 0 -}} + {{ if eq $releasesRootPage.Params.all_releases_root true }} + {{ $sortedVersions := partial "versions-sorted.html" (dict "site" $s "onlyActive" false) -}} + {{ $activeReleases := $s.Params.active_releases }} + + {{ $pagesByVersion := $releasesRootPage.Pages.GroupByParam "release_version" -}} + {{ range $sortedVersions -}} + {{ $version := . -}} + {{ $versionPages := where $pagesByVersion "Key" $version -}} + {{ $versionPage := index ((index $versionPages 0).Pages) 0 }} + {{ if in $activeReleases $version -}} + {{ $activeReleasePages = $activeReleasePages | append $versionPage }} + {{ else -}} + {{ $eolReleasePages = $eolReleasePages | append $versionPage }} + {{ end -}} + {{ end -}} + {{ end -}} +{{ end -}} + +{{ return (dict "active" $activeReleasePages "eol" $eolReleasePages) }} \ No newline at end of file diff --git a/site/layouts/partials/sidebar-releases-tree.html b/site/layouts/partials/sidebar-releases-tree.html new file mode 100644 index 000000000..8e478a823 --- /dev/null +++ b/site/layouts/partials/sidebar-releases-tree.html @@ -0,0 +1,120 @@ +{{/* +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. +*/}} +{{/* We cache this partial for bigger sites and set the active class client side. */ -}} +{{ $sidebarCacheLimit := .Site.Params.ui.sidebar_cache_limit | default 2000 -}} +{{ $shouldDelayActive := ge (len .Site.Pages) $sidebarCacheLimit -}} + +
+ {{ if not .Site.Params.ui.sidebar_search_disable -}} +
+ {{ partial "search-input.html" . }} + +
+ {{ else -}} +
+
+ {{ partial "search-input.html" . }} + +
+
+
+ {{ end -}} + +
+{{/* "outer" tree, starting with the releases pages */}} +{{ define "releases-section-versions-nav-section" -}} +{{ $s := .section -}} +{{ $p := .page -}} +{{ $shouldDelayActive := .shouldDelayActive -}} +{{ $sidebarMenuTruncate := .sidebarMenuTruncate -}} +{{ $ulNr := .ulNr -}} +{{ $ulShow := .ulShow -}} +{{ $pages := .pages -}} +{{ template "releases-section-x-nav-section" (dict "page" $p "section" $s "shouldDelayActive" $shouldDelayActive "sidebarMenuTruncate" $sidebarMenuTruncate "ulNr" $ulNr "ulShow" $ulShow "sectionLinkTitle" .sectionLinkTitle "pages_input" $pages) }} +{{- end -}} + +{{ define "releases-section-x-nav-section" -}} +{{ $s := .section -}} +{{ $p := .page -}} +{{ $shouldDelayActive := .shouldDelayActive -}} +{{ $sidebarMenuTruncate := .sidebarMenuTruncate -}} +{{ $treeRoot := cond (eq .ulNr 0) true false -}} +{{ $ulNr := .ulNr -}} +{{ $ulShow := .ulShow -}} +{{ $active := and (not $shouldDelayActive) (eq $s $p) -}} +{{ $activePath := and (not $shouldDelayActive) (or (eq $p $s) ($p.IsDescendant $s)) -}} +{{ $show := cond (or (lt $ulNr $ulShow) $activePath (and (not $shouldDelayActive) (eq $s.Parent $p.Parent)) (and (not $shouldDelayActive) (eq $s.Parent $p)) (not $p.Site.Params.ui.sidebar_menu_compact) (and (not $shouldDelayActive) ($p.IsDescendant $s.Parent))) true false -}} +{{ $mid := printf "m-%s" ($s.RelPermalink | anchorize) -}} +{{ $pages_input := .pages_input -}} +{{ $pages := $pages_input | first $sidebarMenuTruncate -}} +{{ $truncatedEntryCount := sub (len $pages_input) $sidebarMenuTruncate -}} +{{ if gt $truncatedEntryCount 0 -}} + {{ warnf "WARNING: %d sidebar entries have been truncated. To avoid this, increase `params.ui.sidebar_menu_truncate` to at least %d (from %d) in your config file. Section: %s" + $truncatedEntryCount (len $pages_input) $sidebarMenuTruncate $s.Path -}} +{{ end -}} +{{ $withChild := gt (len $pages) 0 -}} +{{ $manualLink := cond (isset $s.Params "manuallink") $s.Params.manualLink ( cond (isset $s.Params "manuallinkrelref") (relref $s $s.Params.manualLinkRelref) $s.RelPermalink) -}} +{{ $manualLinkTitle := cond (isset $s.Params "manuallinktitle") $s.Params.manualLinkTitle $s.Title -}} +{{ $sectionLinkTitle := .sectionLinkTitle | default $s.LinkTitle }} +
  • + {{ if (and $p.Site.Params.ui.sidebar_menu_foldable (ge $ulNr 1)) -}} + + + {{ else -}} + {{ with $s.Params.Icon}}{{ end }}{{ $sectionLinkTitle }} + {{- end }} + {{- if $withChild }} + {{- $ulNr := add $ulNr 1 }} +
      + {{ range $pages -}} + {{ if (not (and (eq $s $p.Site.Home) (eq .Params.toc_root true))) -}} + {{ $subPages := where .Pages.ByWeight ".Params.toc_hide" "!=" true }} + {{ template "releases-section-x-nav-section" (dict "page" $p "section" . "shouldDelayActive" $shouldDelayActive "sidebarMenuTruncate" $sidebarMenuTruncate "ulNr" $ulNr "ulShow" $ulShow "pages_input" $subPages) }} + {{- end }} + {{- end }} +
    + {{- end }} +
    • +{{- end -}} diff --git a/site/layouts/partials/sidebar-releases.html b/site/layouts/partials/sidebar-releases.html new file mode 100644 index 000000000..7ba8daaf4 --- /dev/null +++ b/site/layouts/partials/sidebar-releases.html @@ -0,0 +1,41 @@ +{{/* +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. +*/}} +{{/* The "active" toggle here may delay rendering, so we only cache this side bar menu for bigger sites. */ -}} +{{ $sidebarCacheLimit := .Site.Params.ui.sidebar_cache_limit | default 2000 -}} +{{ $shouldCache := ge (len .Site.Pages) $sidebarCacheLimit -}} +{{ $sidebarCacheTypeRoot := .Site.Params.ui.sidebar_cache_type_root | default false -}} +{{ if $shouldCache -}} + {{ $mid := printf "m-%s" (.RelPermalink | anchorize) }} + + {{ partialCached "sidebar-releases-tree.html" . .FirstSection.RelPermalink }} +{{ else -}} + {{ partial "sidebar-releases-tree.html" . }} +{{- end }} \ No newline at end of file diff --git a/site/layouts/partials/trimZeroPrefix.html b/site/layouts/partials/trimZeroPrefix.html new file mode 100644 index 000000000..7039c2200 --- /dev/null +++ b/site/layouts/partials/trimZeroPrefix.html @@ -0,0 +1,19 @@ +{{/* +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. +*/}} +{{- return replaceRE "0+(\\d+)" "$1" . }} \ No newline at end of file diff --git a/site/layouts/partials/versions-sorted.html b/site/layouts/partials/versions-sorted.html new file mode 100644 index 000000000..f97596014 --- /dev/null +++ b/site/layouts/partials/versions-sorted.html @@ -0,0 +1,38 @@ +{{/* + 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. +*/}} +{{ $site := .site }} +{{ $onlyActive := .onlyActive }} + +{{ $allVersions := slice }} +{{ if not $onlyActive }} +{{ $releases := where $site.Pages ".Params.release_version" "!=" nil -}} +{{ range $releases -}} +{{ $allVersions = $allVersions | append .Params.release_version }} +{{- end }} +{{ else }} +{{ $allVersions = $site.Params.active_releases }} +{{ end }} + +{{/*- $versions := slice "17.9.200" "17.1.52" "16.8.100" "3.2.3" "3.1.2" "3.10.0" "17.8.20" "3.9.10" "16.8.93" "16.8.201" "17.8.10" "16.8.25-rc.0" "2.8.2" "16.8.21" "16.8.25-rc.2" "16.8.2" "17.21.46" "17.11.42" "20.8.2" "17.9.26" */}} + +{{- $paddedVersions := apply $allVersions "partial" "padZeroPrefix" "." }} +{{- $sortedVersions := (sort $paddedVersions "value" "desc") }} +{{- $sortedVersions = apply $sortedVersions "partial" "trimZeroPrefix" "." }} + +{{- return $sortedVersions }} diff --git a/site/layouts/releases/baseof.html b/site/layouts/releases/baseof.html new file mode 100644 index 000000000..1fc3c131f --- /dev/null +++ b/site/layouts/releases/baseof.html @@ -0,0 +1,48 @@ + + + + {{ partial "head.html" . }} + + +
    + {{ partial "navbar.html" . }} +
    +
    +
    +
    + + {{/* No right sidebar */}} +
    + {{ partial "version-banner.html" . }} + {{ if not .Site.Params.ui.breadcrumb_disable }}{{ partial "breadcrumb.html" . }}{{ end }} + {{ block "main" . }}{{ end }} +
    +
    +
    + {{ partial "footer.html" . }} +
    + {{ partial "scripts.html" . }} + + \ No newline at end of file diff --git a/site/layouts/releases/list.html b/site/layouts/releases/list.html new file mode 100644 index 000000000..6df355c07 --- /dev/null +++ b/site/layouts/releases/list.html @@ -0,0 +1,23 @@ +{{/* + 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 "main" -}} +
    + {{ .Content }} +
    +{{ end }} \ No newline at end of file diff --git a/site/layouts/robots.txt b/site/layouts/robots.txt new file mode 100644 index 000000000..7a6aa7d3a --- /dev/null +++ b/site/layouts/robots.txt @@ -0,0 +1,11 @@ +User-agent: * +{{- $byReleaseVersion := where (.Pages.ByParam "release_version") "ne" nil -}} +{{ $latestRelease := index .Site.Params.active_releases 0 -}} +{{ range $byReleaseVersion -}} + {{ $page := . -}} + {{ with $page.Params.release_version -}} + {{ if ne . $latestRelease }} +Disallow: {{ $page.RelPermalink -}} + {{ end -}} + {{- end -}} +{{- end }} diff --git a/site/layouts/shortcodes/releaseVersion.html b/site/layouts/shortcodes/releaseVersion.html new file mode 100644 index 000000000..7f9540f20 --- /dev/null +++ b/site/layouts/shortcodes/releaseVersion.html @@ -0,0 +1,29 @@ +{{/* +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. +*/}} +{{- $releaseVersion := "[unreleased]" -}} +{{- with .Page.Params.release_version -}} +{{- $releaseVersion = . -}} +{{- else -}} +{{- range .Page.Ancestors -}} +{{- with .Params.release_version -}} +{{- $releaseVersion = . -}} +{{- end -}} +{{- end -}} +{{- end -}} +{{- $releaseVersion -}} \ No newline at end of file diff --git a/site/package-lock.json b/site/package-lock.json new file mode 100644 index 000000000..28da59aa5 --- /dev/null +++ b/site/package-lock.json @@ -0,0 +1,1022 @@ +{ + "name": "site", + "lockfileVersion": 3, + "requires": true, + "packages": { + "": { + "devDependencies": { + "autoprefixer": "^10.4.20", + "postcss": "^8.4.44", + "postcss-cli": "^11.0.0" + } + }, + "node_modules/@nodelib/fs.scandir": { + "version": "2.1.5", + "resolved": "https://registry.npmjs.org/@nodelib/fs.scandir/-/fs.scandir-2.1.5.tgz", + "integrity": "sha512-vq24Bq3ym5HEQm2NKCr3yXDwjc7vTsEThRDnkp2DK9p1uqLR+DHurm/NOTo0KG7HYHU7eppKZj3MyqYuMBf62g==", + "dev": true, + "dependencies": { + "@nodelib/fs.stat": "2.0.5", + "run-parallel": "^1.1.9" + }, + "engines": { + "node": ">= 8" + } + }, + "node_modules/@nodelib/fs.stat": { + "version": "2.0.5", + "resolved": "https://registry.npmjs.org/@nodelib/fs.stat/-/fs.stat-2.0.5.tgz", + "integrity": "sha512-RkhPPp2zrqDAQA/2jNhnztcPAlv64XdhIp7a7454A5ovI7Bukxgt7MX7udwAu3zg1DcpPU0rz3VV1SeaqvY4+A==", + "dev": true, + "engines": { + "node": ">= 8" + } + }, + "node_modules/@nodelib/fs.walk": { + "version": "1.2.8", + "resolved": "https://registry.npmjs.org/@nodelib/fs.walk/-/fs.walk-1.2.8.tgz", + "integrity": "sha512-oGB+UxlgWcgQkgwo8GcEGwemoTFt3FIO9ababBmaGwXIoBKZ+GTy0pP185beGg7Llih/NSHSV2XAs1lnznocSg==", + "dev": true, + "dependencies": { + "@nodelib/fs.scandir": "2.1.5", + "fastq": "^1.6.0" + }, + "engines": { + "node": ">= 8" + } + }, + "node_modules/@sindresorhus/merge-streams": { + "version": "2.3.0", + "resolved": "https://registry.npmjs.org/@sindresorhus/merge-streams/-/merge-streams-2.3.0.tgz", + "integrity": "sha512-LtoMMhxAlorcGhmFYI+LhPgbPZCkgP6ra1YL604EeF6U98pLlQ3iWIGMdWSC+vWmPBWBNgmDBAhnAobLROJmwg==", + "dev": true, + "engines": { + "node": ">=18" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/ansi-regex": { + "version": "5.0.1", + "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-5.0.1.tgz", + "integrity": "sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ==", + "dev": true, + "engines": { + "node": ">=8" + } + }, + "node_modules/ansi-styles": { + "version": "4.3.0", + "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-4.3.0.tgz", + "integrity": "sha512-zbB9rCJAT1rbjiVDb2hqKFHNYLxgtk8NURxZ3IZwD3F6NtxbXZQCnnSi1Lkx+IDohdPlFp222wVALIheZJQSEg==", + "dev": true, + "dependencies": { + "color-convert": "^2.0.1" + }, + "engines": { + "node": ">=8" + }, + "funding": { + "url": "https://github.com/chalk/ansi-styles?sponsor=1" + } + }, + "node_modules/anymatch": { + "version": "3.1.3", + "resolved": "https://registry.npmjs.org/anymatch/-/anymatch-3.1.3.tgz", + "integrity": "sha512-KMReFUr0B4t+D+OBkjR3KYqvocp2XaSzO55UcB6mgQMd3KbcE+mWTyvVV7D/zsdEbNnV6acZUutkiHQXvTr1Rw==", + "dev": true, + "dependencies": { + "normalize-path": "^3.0.0", + "picomatch": "^2.0.4" + }, + "engines": { + "node": ">= 8" + } + }, + "node_modules/autoprefixer": { + "version": "10.4.20", + "resolved": "https://registry.npmjs.org/autoprefixer/-/autoprefixer-10.4.20.tgz", + "integrity": "sha512-XY25y5xSv/wEoqzDyXXME4AFfkZI0P23z6Fs3YgymDnKJkCGOnkL0iTxCa85UTqaSgfcqyf3UA6+c7wUvx/16g==", + "dev": true, + "funding": [ + { + "type": "opencollective", + "url": "https://opencollective.com/postcss/" + }, + { + "type": "tidelift", + "url": "https://tidelift.com/funding/github/npm/autoprefixer" + }, + { + "type": "github", + "url": "https://github.com/sponsors/ai" + } + ], + "dependencies": { + "browserslist": "^4.23.3", + "caniuse-lite": "^1.0.30001646", + "fraction.js": "^4.3.7", + "normalize-range": "^0.1.2", + "picocolors": "^1.0.1", + "postcss-value-parser": "^4.2.0" + }, + "bin": { + "autoprefixer": "bin/autoprefixer" + }, + "engines": { + "node": "^10 || ^12 || >=14" + }, + "peerDependencies": { + "postcss": "^8.1.0" + } + }, + "node_modules/binary-extensions": { + "version": "2.3.0", + "resolved": "https://registry.npmjs.org/binary-extensions/-/binary-extensions-2.3.0.tgz", + "integrity": "sha512-Ceh+7ox5qe7LJuLHoY0feh3pHuUDHAcRUeyL2VYghZwfpkNIy/+8Ocg0a3UuSoYzavmylwuLWQOf3hl0jjMMIw==", + "dev": true, + "engines": { + "node": ">=8" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/braces": { + "version": "3.0.3", + "resolved": "https://registry.npmjs.org/braces/-/braces-3.0.3.tgz", + "integrity": "sha512-yQbXgO/OSZVD2IsiLlro+7Hf6Q18EJrKSEsdoMzKePKXct3gvD8oLcOQdIzGupr5Fj+EDe8gO/lxc1BzfMpxvA==", + "dev": true, + "dependencies": { + "fill-range": "^7.1.1" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/browserslist": { + "version": "4.23.3", + "resolved": "https://registry.npmjs.org/browserslist/-/browserslist-4.23.3.tgz", + "integrity": "sha512-btwCFJVjI4YWDNfau8RhZ+B1Q/VLoUITrm3RlP6y1tYGWIOa+InuYiRGXUBXo8nA1qKmHMyLB/iVQg5TT4eFoA==", + "dev": true, + "funding": [ + { + "type": "opencollective", + "url": "https://opencollective.com/browserslist" + }, + { + "type": "tidelift", + "url": "https://tidelift.com/funding/github/npm/browserslist" + }, + { + "type": "github", + "url": "https://github.com/sponsors/ai" + } + ], + "dependencies": { + "caniuse-lite": "^1.0.30001646", + "electron-to-chromium": "^1.5.4", + "node-releases": "^2.0.18", + "update-browserslist-db": "^1.1.0" + }, + "bin": { + "browserslist": "cli.js" + }, + "engines": { + "node": "^6 || ^7 || ^8 || ^9 || ^10 || ^11 || ^12 || >=13.7" + } + }, + "node_modules/caniuse-lite": { + "version": "1.0.30001655", + "resolved": "https://registry.npmjs.org/caniuse-lite/-/caniuse-lite-1.0.30001655.tgz", + "integrity": "sha512-jRGVy3iSGO5Uutn2owlb5gR6qsGngTw9ZTb4ali9f3glshcNmJ2noam4Mo9zia5P9Dk3jNNydy7vQjuE5dQmfg==", + "dev": true, + "funding": [ + { + "type": "opencollective", + "url": "https://opencollective.com/browserslist" + }, + { + "type": "tidelift", + "url": "https://tidelift.com/funding/github/npm/caniuse-lite" + }, + { + "type": "github", + "url": "https://github.com/sponsors/ai" + } + ] + }, + "node_modules/chokidar": { + "version": "3.6.0", + "resolved": "https://registry.npmjs.org/chokidar/-/chokidar-3.6.0.tgz", + "integrity": "sha512-7VT13fmjotKpGipCW9JEQAusEPE+Ei8nl6/g4FBAmIm0GOOLMua9NDDo/DWp0ZAxCr3cPq5ZpBqmPAQgDda2Pw==", + "dev": true, + "dependencies": { + "anymatch": "~3.1.2", + "braces": "~3.0.2", + "glob-parent": "~5.1.2", + "is-binary-path": "~2.1.0", + "is-glob": "~4.0.1", + "normalize-path": "~3.0.0", + "readdirp": "~3.6.0" + }, + "engines": { + "node": ">= 8.10.0" + }, + "funding": { + "url": "https://paulmillr.com/funding/" + }, + "optionalDependencies": { + "fsevents": "~2.3.2" + } + }, + "node_modules/cliui": { + "version": "8.0.1", + "resolved": "https://registry.npmjs.org/cliui/-/cliui-8.0.1.tgz", + "integrity": "sha512-BSeNnyus75C4//NQ9gQt1/csTXyo/8Sb+afLAkzAptFuMsod9HFokGNudZpi/oQV73hnVK+sR+5PVRMd+Dr7YQ==", + "dev": true, + "dependencies": { + "string-width": "^4.2.0", + "strip-ansi": "^6.0.1", + "wrap-ansi": "^7.0.0" + }, + "engines": { + "node": ">=12" + } + }, + "node_modules/color-convert": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/color-convert/-/color-convert-2.0.1.tgz", + "integrity": "sha512-RRECPsj7iu/xb5oKYcsFHSppFNnsj/52OVTRKb4zP5onXwVF3zVmmToNcOfGC+CRDpfK/U584fMg38ZHCaElKQ==", + "dev": true, + "dependencies": { + "color-name": "~1.1.4" + }, + "engines": { + "node": ">=7.0.0" + } + }, + "node_modules/color-name": { + "version": "1.1.4", + "resolved": "https://registry.npmjs.org/color-name/-/color-name-1.1.4.tgz", + "integrity": "sha512-dOy+3AuW3a2wNbZHIuMZpTcgjGuLU/uBL/ubcZF9OXbDo8ff4O8yVp5Bf0efS8uEoYo5q4Fx7dY9OgQGXgAsQA==", + "dev": true + }, + "node_modules/dependency-graph": { + "version": "0.11.0", + "resolved": "https://registry.npmjs.org/dependency-graph/-/dependency-graph-0.11.0.tgz", + "integrity": "sha512-JeMq7fEshyepOWDfcfHK06N3MhyPhz++vtqWhMT5O9A3K42rdsEDpfdVqjaqaAhsw6a+ZqeDvQVtD0hFHQWrzg==", + "dev": true, + "engines": { + "node": ">= 0.6.0" + } + }, + "node_modules/electron-to-chromium": { + "version": "1.5.13", + "resolved": "https://registry.npmjs.org/electron-to-chromium/-/electron-to-chromium-1.5.13.tgz", + "integrity": "sha512-lbBcvtIJ4J6sS4tb5TLp1b4LyfCdMkwStzXPyAgVgTRAsep4bvrAGaBOP7ZJtQMNJpSQ9SqG4brWOroNaQtm7Q==", + "dev": true + }, + "node_modules/emoji-regex": { + "version": "8.0.0", + "resolved": "https://registry.npmjs.org/emoji-regex/-/emoji-regex-8.0.0.tgz", + "integrity": "sha512-MSjYzcWNOA0ewAHpz0MxpYFvwg6yjy1NG3xteoqz644VCo/RPgnr1/GGt+ic3iJTzQ8Eu3TdM14SawnVUmGE6A==", + "dev": true + }, + "node_modules/escalade": { + "version": "3.2.0", + "resolved": "https://registry.npmjs.org/escalade/-/escalade-3.2.0.tgz", + "integrity": "sha512-WUj2qlxaQtO4g6Pq5c29GTcWGDyd8itL8zTlipgECz3JesAiiOKotd8JU6otB3PACgG6xkJUyVhboMS+bje/jA==", + "dev": true, + "engines": { + "node": ">=6" + } + }, + "node_modules/fast-glob": { + "version": "3.3.2", + "resolved": "https://registry.npmjs.org/fast-glob/-/fast-glob-3.3.2.tgz", + "integrity": "sha512-oX2ruAFQwf/Orj8m737Y5adxDQO0LAB7/S5MnxCdTNDd4p6BsyIVsv9JQsATbTSq8KHRpLwIHbVlUNatxd+1Ow==", + "dev": true, + "dependencies": { + "@nodelib/fs.stat": "^2.0.2", + "@nodelib/fs.walk": "^1.2.3", + "glob-parent": "^5.1.2", + "merge2": "^1.3.0", + "micromatch": "^4.0.4" + }, + "engines": { + "node": ">=8.6.0" + } + }, + "node_modules/fastq": { + "version": "1.17.1", + "resolved": "https://registry.npmjs.org/fastq/-/fastq-1.17.1.tgz", + "integrity": "sha512-sRVD3lWVIXWg6By68ZN7vho9a1pQcN/WBFaAAsDDFzlJjvoGx0P8z7V1t72grFJfJhu3YPZBuu25f7Kaw2jN1w==", + "dev": true, + "dependencies": { + "reusify": "^1.0.4" + } + }, + "node_modules/fill-range": { + "version": "7.1.1", + "resolved": "https://registry.npmjs.org/fill-range/-/fill-range-7.1.1.tgz", + "integrity": "sha512-YsGpe3WHLK8ZYi4tWDg2Jy3ebRz2rXowDxnld4bkQB00cc/1Zw9AWnC0i9ztDJitivtQvaI9KaLyKrc+hBW0yg==", + "dev": true, + "dependencies": { + "to-regex-range": "^5.0.1" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/fraction.js": { + "version": "4.3.7", + "resolved": "https://registry.npmjs.org/fraction.js/-/fraction.js-4.3.7.tgz", + "integrity": "sha512-ZsDfxO51wGAXREY55a7la9LScWpwv9RxIrYABrlvOFBlH/ShPnrtsXeuUIfXKKOVicNxQ+o8JTbJvjS4M89yew==", + "dev": true, + "engines": { + "node": "*" + }, + "funding": { + "type": "patreon", + "url": "https://github.com/sponsors/rawify" + } + }, + "node_modules/fs-extra": { + "version": "11.2.0", + "resolved": "https://registry.npmjs.org/fs-extra/-/fs-extra-11.2.0.tgz", + "integrity": "sha512-PmDi3uwK5nFuXh7XDTlVnS17xJS7vW36is2+w3xcv8SVxiB4NyATf4ctkVY5bkSjX0Y4nbvZCq1/EjtEyr9ktw==", + "dev": true, + "dependencies": { + "graceful-fs": "^4.2.0", + "jsonfile": "^6.0.1", + "universalify": "^2.0.0" + }, + "engines": { + "node": ">=14.14" + } + }, + "node_modules/fsevents": { + "version": "2.3.3", + "resolved": "https://registry.npmjs.org/fsevents/-/fsevents-2.3.3.tgz", + "integrity": "sha512-5xoDfX+fL7faATnagmWPpbFtwh/R77WmMMqqHGS65C3vvB0YHrgF+B1YmZ3441tMj5n63k0212XNoJwzlhffQw==", + "dev": true, + "hasInstallScript": true, + "optional": true, + "os": [ + "darwin" + ], + "engines": { + "node": "^8.16.0 || ^10.6.0 || >=11.0.0" + } + }, + "node_modules/get-caller-file": { + "version": "2.0.5", + "resolved": "https://registry.npmjs.org/get-caller-file/-/get-caller-file-2.0.5.tgz", + "integrity": "sha512-DyFP3BM/3YHTQOCUL/w0OZHR0lpKeGrxotcHWcqNEdnltqFwXVfhEBQ94eIo34AfQpo0rGki4cyIiftY06h2Fg==", + "dev": true, + "engines": { + "node": "6.* || 8.* || >= 10.*" + } + }, + "node_modules/get-stdin": { + "version": "9.0.0", + "resolved": "https://registry.npmjs.org/get-stdin/-/get-stdin-9.0.0.tgz", + "integrity": "sha512-dVKBjfWisLAicarI2Sf+JuBE/DghV4UzNAVe9yhEJuzeREd3JhOTE9cUaJTeSa77fsbQUK3pcOpJfM59+VKZaA==", + "dev": true, + "engines": { + "node": ">=12" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/glob-parent": { + "version": "5.1.2", + "resolved": "https://registry.npmjs.org/glob-parent/-/glob-parent-5.1.2.tgz", + "integrity": "sha512-AOIgSQCepiJYwP3ARnGx+5VnTu2HBYdzbGP45eLw1vr3zB3vZLeyed1sC9hnbcOc9/SrMyM5RPQrkGz4aS9Zow==", + "dev": true, + "dependencies": { + "is-glob": "^4.0.1" + }, + "engines": { + "node": ">= 6" + } + }, + "node_modules/globby": { + "version": "14.0.2", + "resolved": "https://registry.npmjs.org/globby/-/globby-14.0.2.tgz", + "integrity": "sha512-s3Fq41ZVh7vbbe2PN3nrW7yC7U7MFVc5c98/iTl9c2GawNMKx/J648KQRW6WKkuU8GIbbh2IXfIRQjOZnXcTnw==", + "dev": true, + "dependencies": { + "@sindresorhus/merge-streams": "^2.1.0", + "fast-glob": "^3.3.2", + "ignore": "^5.2.4", + "path-type": "^5.0.0", + "slash": "^5.1.0", + "unicorn-magic": "^0.1.0" + }, + "engines": { + "node": ">=18" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/graceful-fs": { + "version": "4.2.11", + "resolved": "https://registry.npmjs.org/graceful-fs/-/graceful-fs-4.2.11.tgz", + "integrity": "sha512-RbJ5/jmFcNNCcDV5o9eTnBLJ/HszWV0P73bc+Ff4nS/rJj+YaS6IGyiOL0VoBYX+l1Wrl3k63h/KrH+nhJ0XvQ==", + "dev": true + }, + "node_modules/ignore": { + "version": "5.3.2", + "resolved": "https://registry.npmjs.org/ignore/-/ignore-5.3.2.tgz", + "integrity": "sha512-hsBTNUqQTDwkWtcdYI2i06Y/nUBEsNEDJKjWdigLvegy8kDuJAS8uRlpkkcQpyEXL0Z/pjDy5HBmMjRCJ2gq+g==", + "dev": true, + "engines": { + "node": ">= 4" + } + }, + "node_modules/is-binary-path": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/is-binary-path/-/is-binary-path-2.1.0.tgz", + "integrity": "sha512-ZMERYes6pDydyuGidse7OsHxtbI7WVeUEozgR/g7rd0xUimYNlvZRE/K2MgZTjWy725IfelLeVcEM97mmtRGXw==", + "dev": true, + "dependencies": { + "binary-extensions": "^2.0.0" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/is-extglob": { + "version": "2.1.1", + "resolved": "https://registry.npmjs.org/is-extglob/-/is-extglob-2.1.1.tgz", + "integrity": "sha512-SbKbANkN603Vi4jEZv49LeVJMn4yGwsbzZworEoyEiutsN3nJYdbO36zfhGJ6QEDpOZIFkDtnq5JRxmvl3jsoQ==", + "dev": true, + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/is-fullwidth-code-point": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/is-fullwidth-code-point/-/is-fullwidth-code-point-3.0.0.tgz", + "integrity": "sha512-zymm5+u+sCsSWyD9qNaejV3DFvhCKclKdizYaJUuHA83RLjb7nSuGnddCHGv0hk+KY7BMAlsWeK4Ueg6EV6XQg==", + "dev": true, + "engines": { + "node": ">=8" + } + }, + "node_modules/is-glob": { + "version": "4.0.3", + "resolved": "https://registry.npmjs.org/is-glob/-/is-glob-4.0.3.tgz", + "integrity": "sha512-xelSayHH36ZgE7ZWhli7pW34hNbNl8Ojv5KVmkJD4hBdD3th8Tfk9vYasLM+mXWOZhFkgZfxhLSnrwRr4elSSg==", + "dev": true, + "dependencies": { + "is-extglob": "^2.1.1" + }, + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/is-number": { + "version": "7.0.0", + "resolved": "https://registry.npmjs.org/is-number/-/is-number-7.0.0.tgz", + "integrity": "sha512-41Cifkg6e8TylSpdtTpeLVMqvSBEVzTttHvERD741+pnZ8ANv0004MRL43QKPDlK9cGvNp6NZWZUBlbGXYxxng==", + "dev": true, + "engines": { + "node": ">=0.12.0" + } + }, + "node_modules/jsonfile": { + "version": "6.1.0", + "resolved": "https://registry.npmjs.org/jsonfile/-/jsonfile-6.1.0.tgz", + "integrity": "sha512-5dgndWOriYSm5cnYaJNhalLNDKOqFwyDB/rr1E9ZsGciGvKPs8R2xYGCacuf3z6K1YKDz182fd+fY3cn3pMqXQ==", + "dev": true, + "dependencies": { + "universalify": "^2.0.0" + }, + "optionalDependencies": { + "graceful-fs": "^4.1.6" + } + }, + "node_modules/lilconfig": { + "version": "3.1.2", + "resolved": "https://registry.npmjs.org/lilconfig/-/lilconfig-3.1.2.tgz", + "integrity": "sha512-eop+wDAvpItUys0FWkHIKeC9ybYrTGbU41U5K7+bttZZeohvnY7M9dZ5kB21GNWiFT2q1OoPTvncPCgSOVO5ow==", + "dev": true, + "engines": { + "node": ">=14" + }, + "funding": { + "url": "https://github.com/sponsors/antonk52" + } + }, + "node_modules/merge2": { + "version": "1.4.1", + "resolved": "https://registry.npmjs.org/merge2/-/merge2-1.4.1.tgz", + "integrity": "sha512-8q7VEgMJW4J8tcfVPy8g09NcQwZdbwFEqhe/WZkoIzjn/3TGDwtOCYtXGxA3O8tPzpczCCDgv+P2P5y00ZJOOg==", + "dev": true, + "engines": { + "node": ">= 8" + } + }, + "node_modules/micromatch": { + "version": "4.0.8", + "resolved": "https://registry.npmjs.org/micromatch/-/micromatch-4.0.8.tgz", + "integrity": "sha512-PXwfBhYu0hBCPw8Dn0E+WDYb7af3dSLVWKi3HGv84IdF4TyFoC0ysxFd0Goxw7nSv4T/PzEJQxsYsEiFCKo2BA==", + "dev": true, + "dependencies": { + "braces": "^3.0.3", + "picomatch": "^2.3.1" + }, + "engines": { + "node": ">=8.6" + } + }, + "node_modules/nanoid": { + "version": "3.3.7", + "resolved": "https://registry.npmjs.org/nanoid/-/nanoid-3.3.7.tgz", + "integrity": "sha512-eSRppjcPIatRIMC1U6UngP8XFcz8MQWGQdt1MTBQ7NaAmvXDfvNxbvWV3x2y6CdEUciCSsDHDQZbhYaB8QEo2g==", + "dev": true, + "funding": [ + { + "type": "github", + "url": "https://github.com/sponsors/ai" + } + ], + "bin": { + "nanoid": "bin/nanoid.cjs" + }, + "engines": { + "node": "^10 || ^12 || ^13.7 || ^14 || >=15.0.1" + } + }, + "node_modules/node-releases": { + "version": "2.0.18", + "resolved": "https://registry.npmjs.org/node-releases/-/node-releases-2.0.18.tgz", + "integrity": "sha512-d9VeXT4SJ7ZeOqGX6R5EM022wpL+eWPooLI+5UpWn2jCT1aosUQEhQP214x33Wkwx3JQMvIm+tIoVOdodFS40g==", + "dev": true + }, + "node_modules/normalize-path": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/normalize-path/-/normalize-path-3.0.0.tgz", + "integrity": "sha512-6eZs5Ls3WtCisHWp9S2GUy8dqkpGi4BVSz3GaqiE6ezub0512ESztXUwUB6C6IKbQkY2Pnb/mD4WYojCRwcwLA==", + "dev": true, + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/normalize-range": { + "version": "0.1.2", + "resolved": "https://registry.npmjs.org/normalize-range/-/normalize-range-0.1.2.tgz", + "integrity": "sha512-bdok/XvKII3nUpklnV6P2hxtMNrCboOjAcyBuQnWEhO665FwrSNRxU+AqpsyvO6LgGYPspN+lu5CLtw4jPRKNA==", + "dev": true, + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/path-type": { + "version": "5.0.0", + "resolved": "https://registry.npmjs.org/path-type/-/path-type-5.0.0.tgz", + "integrity": "sha512-5HviZNaZcfqP95rwpv+1HDgUamezbqdSYTyzjTvwtJSnIH+3vnbmWsItli8OFEndS984VT55M3jduxZbX351gg==", + "dev": true, + "engines": { + "node": ">=12" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/picocolors": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/picocolors/-/picocolors-1.1.0.tgz", + "integrity": "sha512-TQ92mBOW0l3LeMeyLV6mzy/kWr8lkd/hp3mTg7wYK7zJhuBStmGMBG0BdeDZS/dZx1IukaX6Bk11zcln25o1Aw==", + "dev": true + }, + "node_modules/picomatch": { + "version": "2.3.1", + "resolved": "https://registry.npmjs.org/picomatch/-/picomatch-2.3.1.tgz", + "integrity": "sha512-JU3teHTNjmE2VCGFzuY8EXzCDVwEqB2a8fsIvwaStHhAWJEeVd1o1QD80CU6+ZdEXXSLbSsuLwJjkCBWqRQUVA==", + "dev": true, + "engines": { + "node": ">=8.6" + }, + "funding": { + "url": "https://github.com/sponsors/jonschlinkert" + } + }, + "node_modules/pify": { + "version": "2.3.0", + "resolved": "https://registry.npmjs.org/pify/-/pify-2.3.0.tgz", + "integrity": "sha512-udgsAY+fTnvv7kI7aaxbqwWNb0AHiB0qBO89PZKPkoTmGOgdbrHDKD+0B2X4uTfJ/FT1R09r9gTsjUjNJotuog==", + "dev": true, + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/postcss": { + "version": "8.4.44", + "resolved": "https://registry.npmjs.org/postcss/-/postcss-8.4.44.tgz", + "integrity": "sha512-Aweb9unOEpQ3ezu4Q00DPvvM2ZTUitJdNKeP/+uQgr1IBIqu574IaZoURId7BKtWMREwzKa9OgzPzezWGPWFQw==", + "dev": true, + "funding": [ + { + "type": "opencollective", + "url": "https://opencollective.com/postcss/" + }, + { + "type": "tidelift", + "url": "https://tidelift.com/funding/github/npm/postcss" + }, + { + "type": "github", + "url": "https://github.com/sponsors/ai" + } + ], + "dependencies": { + "nanoid": "^3.3.7", + "picocolors": "^1.0.1", + "source-map-js": "^1.2.0" + }, + "engines": { + "node": "^10 || ^12 || >=14" + } + }, + "node_modules/postcss-cli": { + "version": "11.0.0", + "resolved": "https://registry.npmjs.org/postcss-cli/-/postcss-cli-11.0.0.tgz", + "integrity": "sha512-xMITAI7M0u1yolVcXJ9XTZiO9aO49mcoKQy6pCDFdMh9kGqhzLVpWxeD/32M/QBmkhcGypZFFOLNLmIW4Pg4RA==", + "dev": true, + "dependencies": { + "chokidar": "^3.3.0", + "dependency-graph": "^0.11.0", + "fs-extra": "^11.0.0", + "get-stdin": "^9.0.0", + "globby": "^14.0.0", + "picocolors": "^1.0.0", + "postcss-load-config": "^5.0.0", + "postcss-reporter": "^7.0.0", + "pretty-hrtime": "^1.0.3", + "read-cache": "^1.0.0", + "slash": "^5.0.0", + "yargs": "^17.0.0" + }, + "bin": { + "postcss": "index.js" + }, + "engines": { + "node": ">=18" + }, + "peerDependencies": { + "postcss": "^8.0.0" + } + }, + "node_modules/postcss-load-config": { + "version": "5.1.0", + "resolved": "https://registry.npmjs.org/postcss-load-config/-/postcss-load-config-5.1.0.tgz", + "integrity": "sha512-G5AJ+IX0aD0dygOE0yFZQ/huFFMSNneyfp0e3/bT05a8OfPC5FUoZRPfGijUdGOJNMewJiwzcHJXFafFzeKFVA==", + "dev": true, + "funding": [ + { + "type": "opencollective", + "url": "https://opencollective.com/postcss/" + }, + { + "type": "github", + "url": "https://github.com/sponsors/ai" + } + ], + "dependencies": { + "lilconfig": "^3.1.1", + "yaml": "^2.4.2" + }, + "engines": { + "node": ">= 18" + }, + "peerDependencies": { + "jiti": ">=1.21.0", + "postcss": ">=8.0.9", + "tsx": "^4.8.1" + }, + "peerDependenciesMeta": { + "jiti": { + "optional": true + }, + "postcss": { + "optional": true + }, + "tsx": { + "optional": true + } + } + }, + "node_modules/postcss-reporter": { + "version": "7.1.0", + "resolved": "https://registry.npmjs.org/postcss-reporter/-/postcss-reporter-7.1.0.tgz", + "integrity": "sha512-/eoEylGWyy6/DOiMP5lmFRdmDKThqgn7D6hP2dXKJI/0rJSO1ADFNngZfDzxL0YAxFvws+Rtpuji1YIHj4mySA==", + "dev": true, + "funding": [ + { + "type": "opencollective", + "url": "https://opencollective.com/postcss/" + }, + { + "type": "github", + "url": "https://github.com/sponsors/ai" + } + ], + "dependencies": { + "picocolors": "^1.0.0", + "thenby": "^1.3.4" + }, + "engines": { + "node": ">=10" + }, + "peerDependencies": { + "postcss": "^8.1.0" + } + }, + "node_modules/postcss-value-parser": { + "version": "4.2.0", + "resolved": "https://registry.npmjs.org/postcss-value-parser/-/postcss-value-parser-4.2.0.tgz", + "integrity": "sha512-1NNCs6uurfkVbeXG4S8JFT9t19m45ICnif8zWLd5oPSZ50QnwMfK+H3jv408d4jw/7Bttv5axS5IiHoLaVNHeQ==", + "dev": true + }, + "node_modules/pretty-hrtime": { + "version": "1.0.3", + "resolved": "https://registry.npmjs.org/pretty-hrtime/-/pretty-hrtime-1.0.3.tgz", + "integrity": "sha512-66hKPCr+72mlfiSjlEB1+45IjXSqvVAIy6mocupoww4tBFE9R9IhwwUGoI4G++Tc9Aq+2rxOt0RFU6gPcrte0A==", + "dev": true, + "engines": { + "node": ">= 0.8" + } + }, + "node_modules/queue-microtask": { + "version": "1.2.3", + "resolved": "https://registry.npmjs.org/queue-microtask/-/queue-microtask-1.2.3.tgz", + "integrity": "sha512-NuaNSa6flKT5JaSYQzJok04JzTL1CA6aGhv5rfLW3PgqA+M2ChpZQnAC8h8i4ZFkBS8X5RqkDBHA7r4hej3K9A==", + "dev": true, + "funding": [ + { + "type": "github", + "url": "https://github.com/sponsors/feross" + }, + { + "type": "patreon", + "url": "https://www.patreon.com/feross" + }, + { + "type": "consulting", + "url": "https://feross.org/support" + } + ] + }, + "node_modules/read-cache": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/read-cache/-/read-cache-1.0.0.tgz", + "integrity": "sha512-Owdv/Ft7IjOgm/i0xvNDZ1LrRANRfew4b2prF3OWMQLxLfu3bS8FVhCsrSCMK4lR56Y9ya+AThoTpDCTxCmpRA==", + "dev": true, + "dependencies": { + "pify": "^2.3.0" + } + }, + "node_modules/readdirp": { + "version": "3.6.0", + "resolved": "https://registry.npmjs.org/readdirp/-/readdirp-3.6.0.tgz", + "integrity": "sha512-hOS089on8RduqdbhvQ5Z37A0ESjsqz6qnRcffsMU3495FuTdqSm+7bhJ29JvIOsBDEEnan5DPu9t3To9VRlMzA==", + "dev": true, + "dependencies": { + "picomatch": "^2.2.1" + }, + "engines": { + "node": ">=8.10.0" + } + }, + "node_modules/require-directory": { + "version": "2.1.1", + "resolved": "https://registry.npmjs.org/require-directory/-/require-directory-2.1.1.tgz", + "integrity": "sha512-fGxEI7+wsG9xrvdjsrlmL22OMTTiHRwAMroiEeMgq8gzoLC/PQr7RsRDSTLUg/bZAZtF+TVIkHc6/4RIKrui+Q==", + "dev": true, + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/reusify": { + "version": "1.0.4", + "resolved": "https://registry.npmjs.org/reusify/-/reusify-1.0.4.tgz", + "integrity": "sha512-U9nH88a3fc/ekCF1l0/UP1IosiuIjyTh7hBvXVMHYgVcfGvt897Xguj2UOLDeI5BG2m7/uwyaLVT6fbtCwTyzw==", + "dev": true, + "engines": { + "iojs": ">=1.0.0", + "node": ">=0.10.0" + } + }, + "node_modules/run-parallel": { + "version": "1.2.0", + "resolved": "https://registry.npmjs.org/run-parallel/-/run-parallel-1.2.0.tgz", + "integrity": "sha512-5l4VyZR86LZ/lDxZTR6jqL8AFE2S0IFLMP26AbjsLVADxHdhB/c0GUsH+y39UfCi3dzz8OlQuPmnaJOMoDHQBA==", + "dev": true, + "funding": [ + { + "type": "github", + "url": "https://github.com/sponsors/feross" + }, + { + "type": "patreon", + "url": "https://www.patreon.com/feross" + }, + { + "type": "consulting", + "url": "https://feross.org/support" + } + ], + "dependencies": { + "queue-microtask": "^1.2.2" + } + }, + "node_modules/slash": { + "version": "5.1.0", + "resolved": "https://registry.npmjs.org/slash/-/slash-5.1.0.tgz", + "integrity": "sha512-ZA6oR3T/pEyuqwMgAKT0/hAv8oAXckzbkmR0UkUosQ+Mc4RxGoJkRmwHgHufaenlyAgE1Mxgpdcrf75y6XcnDg==", + "dev": true, + "engines": { + "node": ">=14.16" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/source-map-js": { + "version": "1.2.0", + "resolved": "https://registry.npmjs.org/source-map-js/-/source-map-js-1.2.0.tgz", + "integrity": "sha512-itJW8lvSA0TXEphiRoawsCksnlf8SyvmFzIhltqAHluXd88pkCd+cXJVHTDwdCr0IzwptSm035IHQktUu1QUMg==", + "dev": true, + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/string-width": { + "version": "4.2.3", + "resolved": "https://registry.npmjs.org/string-width/-/string-width-4.2.3.tgz", + "integrity": "sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g==", + "dev": true, + "dependencies": { + "emoji-regex": "^8.0.0", + "is-fullwidth-code-point": "^3.0.0", + "strip-ansi": "^6.0.1" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/strip-ansi": { + "version": "6.0.1", + "resolved": "https://registry.npmjs.org/strip-ansi/-/strip-ansi-6.0.1.tgz", + "integrity": "sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A==", + "dev": true, + "dependencies": { + "ansi-regex": "^5.0.1" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/thenby": { + "version": "1.3.4", + "resolved": "https://registry.npmjs.org/thenby/-/thenby-1.3.4.tgz", + "integrity": "sha512-89Gi5raiWA3QZ4b2ePcEwswC3me9JIg+ToSgtE0JWeCynLnLxNr/f9G+xfo9K+Oj4AFdom8YNJjibIARTJmapQ==", + "dev": true + }, + "node_modules/to-regex-range": { + "version": "5.0.1", + "resolved": "https://registry.npmjs.org/to-regex-range/-/to-regex-range-5.0.1.tgz", + "integrity": "sha512-65P7iz6X5yEr1cwcgvQxbbIw7Uk3gOy5dIdtZ4rDveLqhrdJP+Li/Hx6tyK0NEb+2GCyneCMJiGqrADCSNk8sQ==", + "dev": true, + "dependencies": { + "is-number": "^7.0.0" + }, + "engines": { + "node": ">=8.0" + } + }, + "node_modules/unicorn-magic": { + "version": "0.1.0", + "resolved": "https://registry.npmjs.org/unicorn-magic/-/unicorn-magic-0.1.0.tgz", + "integrity": "sha512-lRfVq8fE8gz6QMBuDM6a+LO3IAzTi05H6gCVaUpir2E1Rwpo4ZUog45KpNXKC/Mn3Yb9UDuHumeFTo9iV/D9FQ==", + "dev": true, + "engines": { + "node": ">=18" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/universalify": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/universalify/-/universalify-2.0.1.tgz", + "integrity": "sha512-gptHNQghINnc/vTGIk0SOFGFNXw7JVrlRUtConJRlvaw6DuX0wO5Jeko9sWrMBhh+PsYAZ7oXAiOnf/UKogyiw==", + "dev": true, + "engines": { + "node": ">= 10.0.0" + } + }, + "node_modules/update-browserslist-db": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/update-browserslist-db/-/update-browserslist-db-1.1.0.tgz", + "integrity": "sha512-EdRAaAyk2cUE1wOf2DkEhzxqOQvFOoRJFNS6NeyJ01Gp2beMRpBAINjM2iDXE3KCuKhwnvHIQCJm6ThL2Z+HzQ==", + "dev": true, + "funding": [ + { + "type": "opencollective", + "url": "https://opencollective.com/browserslist" + }, + { + "type": "tidelift", + "url": "https://tidelift.com/funding/github/npm/browserslist" + }, + { + "type": "github", + "url": "https://github.com/sponsors/ai" + } + ], + "dependencies": { + "escalade": "^3.1.2", + "picocolors": "^1.0.1" + }, + "bin": { + "update-browserslist-db": "cli.js" + }, + "peerDependencies": { + "browserslist": ">= 4.21.0" + } + }, + "node_modules/wrap-ansi": { + "version": "7.0.0", + "resolved": "https://registry.npmjs.org/wrap-ansi/-/wrap-ansi-7.0.0.tgz", + "integrity": "sha512-YVGIj2kamLSTxw6NsZjoBxfSwsn0ycdesmc4p+Q21c5zPuZ1pl+NfxVdxPtdHvmNVOQ6XSYG4AUtyt/Fi7D16Q==", + "dev": true, + "dependencies": { + "ansi-styles": "^4.0.0", + "string-width": "^4.1.0", + "strip-ansi": "^6.0.0" + }, + "engines": { + "node": ">=10" + }, + "funding": { + "url": "https://github.com/chalk/wrap-ansi?sponsor=1" + } + }, + "node_modules/y18n": { + "version": "5.0.8", + "resolved": "https://registry.npmjs.org/y18n/-/y18n-5.0.8.tgz", + "integrity": "sha512-0pfFzegeDWJHJIAmTLRP2DwHjdF5s7jo9tuztdQxAhINCdvS+3nGINqPd00AphqJR/0LhANUS6/+7SCb98YOfA==", + "dev": true, + "engines": { + "node": ">=10" + } + }, + "node_modules/yaml": { + "version": "2.5.0", + "resolved": "https://registry.npmjs.org/yaml/-/yaml-2.5.0.tgz", + "integrity": "sha512-2wWLbGbYDiSqqIKoPjar3MPgB94ErzCtrNE1FdqGuaO0pi2JGjmE8aW8TDZwzU7vuxcGRdL/4gPQwQ7hD5AMSw==", + "dev": true, + "bin": { + "yaml": "bin.mjs" + }, + "engines": { + "node": ">= 14" + } + }, + "node_modules/yargs": { + "version": "17.7.2", + "resolved": "https://registry.npmjs.org/yargs/-/yargs-17.7.2.tgz", + "integrity": "sha512-7dSzzRQ++CKnNI/krKnYRV7JKKPUXMEh61soaHKg9mrWEhzFWhFnxPxGl+69cD1Ou63C13NUPCnmIcrvqCuM6w==", + "dev": true, + "dependencies": { + "cliui": "^8.0.1", + "escalade": "^3.1.1", + "get-caller-file": "^2.0.5", + "require-directory": "^2.1.1", + "string-width": "^4.2.3", + "y18n": "^5.0.5", + "yargs-parser": "^21.1.1" + }, + "engines": { + "node": ">=12" + } + }, + "node_modules/yargs-parser": { + "version": "21.1.1", + "resolved": "https://registry.npmjs.org/yargs-parser/-/yargs-parser-21.1.1.tgz", + "integrity": "sha512-tVpsJW7DdjecAiFpbIB1e3qxIQsE6NoPc5/eTdrbbIC4h0LVsWhnoa3g+m2HclBIujHzsxZ4VJVA+GUuc2/LBw==", + "dev": true, + "engines": { + "node": ">=12" + } + } + } +} diff --git a/site/package.json b/site/package.json new file mode 100644 index 000000000..db2a61301 --- /dev/null +++ b/site/package.json @@ -0,0 +1,7 @@ +{ + "devDependencies": { + "autoprefixer": "^10.4.20", + "postcss": "^8.4.44", + "postcss-cli": "^11.0.0" + } +} diff --git a/site/postcss.config.js b/site/postcss.config.js new file mode 100644 index 000000000..418d886dd --- /dev/null +++ b/site/postcss.config.js @@ -0,0 +1,23 @@ +/* + * 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. + */ +module.exports = { + plugins: [ + require('autoprefixer') + ] +}; diff --git a/site/static/favicons/favicon.png b/site/static/favicons/favicon.png new file mode 100644 index 000000000..bb92271f7 Binary files /dev/null and b/site/static/favicons/favicon.png differ diff --git a/site/static/images/Polaris-Catalog-BLOG-symmetrical-subhead.png b/site/static/images/Polaris-Catalog-BLOG-symmetrical-subhead.png new file mode 100644 index 000000000..eb941b89e Binary files /dev/null and b/site/static/images/Polaris-Catalog-BLOG-symmetrical-subhead.png differ diff --git a/site/static/images/apache-incubator.svg b/site/static/images/apache-incubator.svg new file mode 100644 index 000000000..1b4c36433 --- /dev/null +++ b/site/static/images/apache-incubator.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/site/static/images/polaris-brandmark.png b/site/static/images/polaris-brandmark.png new file mode 100644 index 000000000..6573f7a61 Binary files /dev/null and b/site/static/images/polaris-brandmark.png differ diff --git a/site/static/images/polaris-catalog-stacked-logo-white.png b/site/static/images/polaris-catalog-stacked-logo-white.png new file mode 100644 index 000000000..464ad452f Binary files /dev/null and b/site/static/images/polaris-catalog-stacked-logo-white.png differ diff --git a/site/static/images/polaris-catalog-stacked-logo-white.svg b/site/static/images/polaris-catalog-stacked-logo-white.svg new file mode 100644 index 000000000..aacc8fe38 --- /dev/null +++ b/site/static/images/polaris-catalog-stacked-logo-white.svg @@ -0,0 +1,17 @@ + + + + + + + + + + + + + + + + + diff --git a/site/static/images/polaris-catalog-stacked-logo.png b/site/static/images/polaris-catalog-stacked-logo.png new file mode 100644 index 000000000..451c85e93 Binary files /dev/null and b/site/static/images/polaris-catalog-stacked-logo.png differ diff --git a/site/static/images/polaris-catalog-stacked-logo.svg b/site/static/images/polaris-catalog-stacked-logo.svg new file mode 100644 index 000000000..b44b0a5d7 --- /dev/null +++ b/site/static/images/polaris-catalog-stacked-logo.svg @@ -0,0 +1,17 @@ + + + + + + + + + + + + + + + + + diff --git a/site/static/img/example-workflow.svg b/site/static/img/example-workflow.svg new file mode 100644 index 000000000..7db3df677 --- /dev/null +++ b/site/static/img/example-workflow.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/site/static/img/logos/Polaris-Catalog-BLOG-symmetrical-subhead.png b/site/static/img/logos/Polaris-Catalog-BLOG-symmetrical-subhead.png new file mode 100644 index 000000000..eb941b89e Binary files /dev/null and b/site/static/img/logos/Polaris-Catalog-BLOG-symmetrical-subhead.png differ diff --git a/site/static/img/logos/polaris-brandmark.png b/site/static/img/logos/polaris-brandmark.png new file mode 100644 index 000000000..6573f7a61 Binary files /dev/null and b/site/static/img/logos/polaris-brandmark.png differ diff --git a/site/static/img/logos/polaris-catalog-stacked-logo.svg b/site/static/img/logos/polaris-catalog-stacked-logo.svg new file mode 100644 index 000000000..b44b0a5d7 --- /dev/null +++ b/site/static/img/logos/polaris-catalog-stacked-logo.svg @@ -0,0 +1,17 @@ + + + + + + + + + + + + + + + + + diff --git a/site/static/img/logos/polaris-favicon.png b/site/static/img/logos/polaris-favicon.png new file mode 100644 index 000000000..bb92271f7 Binary files /dev/null and b/site/static/img/logos/polaris-favicon.png differ diff --git a/site/static/img/overview.svg b/site/static/img/overview.svg new file mode 100644 index 000000000..dbe577490 --- /dev/null +++ b/site/static/img/overview.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/site/static/img/quickstart/privilege-illustration-1.png b/site/static/img/quickstart/privilege-illustration-1.png new file mode 100644 index 000000000..69328caf5 Binary files /dev/null and b/site/static/img/quickstart/privilege-illustration-1.png differ diff --git a/site/static/img/quickstart/privilege-illustration-2.png b/site/static/img/quickstart/privilege-illustration-2.png new file mode 100644 index 000000000..a26428ca6 Binary files /dev/null and b/site/static/img/quickstart/privilege-illustration-2.png differ diff --git a/site/static/img/rbac-example.svg b/site/static/img/rbac-example.svg new file mode 100644 index 000000000..431e30ffb --- /dev/null +++ b/site/static/img/rbac-example.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/site/static/img/rbac-model.svg b/site/static/img/rbac-model.svg new file mode 100644 index 000000000..7c7323d32 --- /dev/null +++ b/site/static/img/rbac-model.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/site/static/img/sample-catalog-structure.svg b/site/static/img/sample-catalog-structure.svg new file mode 100644 index 000000000..efecec6ba --- /dev/null +++ b/site/static/img/sample-catalog-structure.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/site/static/openapi/polaris-management-service.yml b/site/static/openapi/polaris-management-service.yml new file mode 100644 index 000000000..a11f9e04e --- /dev/null +++ b/site/static/openapi/polaris-management-service.yml @@ -0,0 +1,1346 @@ +# 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. + + +openapi: 3.0.3 +info: + title: Polaris Management Service + version: 0.0.1 + description: + Defines the management APIs for using Polaris to create and manage Iceberg catalogs and their principals +servers: + - url: "{scheme}://{host}/api/management/v1" + description: Server URL when the port can be inferred from the scheme + variables: + scheme: + description: The scheme of the URI, either http or https. + default: https + host: + description: The host address for the specified server + default: localhost +# All routes are currently configured using an Authorization header. +security: + - OAuth2: [] + +paths: + /catalogs: + get: + operationId: listCatalogs + description: List all catalogs in this polaris service + responses: + 200: + description: List of catalogs in the polaris service + content: + application/json: + schema: + $ref: "#/components/schemas/Catalogs" + 403: + description: "The caller does not have permission to list catalog details" + post: + operationId: createCatalog + description: Add a new Catalog + requestBody: + description: The Catalog to create + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/CreateCatalogRequest" + responses: + 201: + description: "Successful response" + 403: + description: "The caller does not have permission to create a catalog" + 404: + description: "The catalog does not exist" + 409: + description: "A catalog with the specified name already exists" + + /catalogs/{catalogName}: + parameters: + - name: catalogName + in: path + description: The name of the catalog + required: true + schema: + type: string + minLength: 1 + maxLength: 256 + pattern: '^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$' + get: + operationId: getCatalog + description: Get the details of a catalog + responses: + 200: + description: The catalog details + content: + application/json: + schema: + $ref: "#/components/schemas/Catalog" + 403: + description: "The caller does not have permission to read catalog details" + 404: + description: "The catalog does not exist" + + put: + operationId: updateCatalog + description: Update an existing catalog + requestBody: + description: The catalog details to use in the update + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/UpdateCatalogRequest" + responses: + 200: + description: The catalog details + content: + application/json: + schema: + $ref: "#/components/schemas/Catalog" + 403: + description: "The caller does not have permission to update catalog details" + 404: + description: "The catalog does not exist" + 409: + description: "The entity version doesn't match the currentEntityVersion; retry after fetching latest version" + + delete: + operationId: deleteCatalog + description: Delete an existing catalog. This is a cascading operation that deletes all metadata, including principals, + roles and grants. If the catalog is an internal catalog, all tables and namespaces are dropped without purge. + responses: + 204: + description: "Success, no content" + 403: + description: "The caller does not have permission to delete a catalog" + 404: + description: "The catalog does not exist" + + /principals: + get: + operationId: listPrincipals + description: List the principals for the current catalog + responses: + 200: + description: List of principals for this catalog + content: + application/json: + schema: + $ref: "#/components/schemas/Principals" + 403: + description: "The caller does not have permission to list catalog admins" + 404: + description: "The catalog does not exist" + + post: + operationId: createPrincipal + description: Create a principal + requestBody: + description: The principal to create + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/CreatePrincipalRequest" + responses: + 201: + description: "Successful response" + content: + application/json: + schema: + $ref: "#/components/schemas/PrincipalWithCredentials" + 403: + description: "The caller does not have permission to add a principal" + + /principals/{principalName}: + parameters: + - name: principalName + in: path + description: The principal name + required: true + schema: + type: string + minLength: 1 + maxLength: 256 + pattern: '^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$' + get: + operationId: getPrincipal + description: Get the principal details + responses: + 200: + description: The requested principal + content: + application/json: + schema: + $ref: "#/components/schemas/Principal" + 403: + description: "The caller does not have permission to get principal details" + 404: + description: "The catalog or principal does not exist" + + put: + operationId: updatePrincipal + description: Update an existing principal + requestBody: + description: The principal details to use in the update + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/UpdatePrincipalRequest" + responses: + 200: + description: The updated principal + content: + application/json: + schema: + $ref: "#/components/schemas/Principal" + 403: + description: "The caller does not have permission to update principal details" + 404: + description: "The principal does not exist" + 409: + description: "The entity version doesn't match the currentEntityVersion; retry after fetching latest version" + + delete: + operationId: deletePrincipal + description: Remove a principal from polaris + responses: + 204: + description: "Success, no content" + 403: + description: "The caller does not have permission to delete a principal" + 404: + description: "The principal does not exist" + + /principals/{principalName}/rotate: + parameters: + - name: principalName + in: path + description: The user name + required: true + schema: + type: string + minLength: 1 + maxLength: 256 + pattern: '^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$' + post: + operationId: rotateCredentials + description: Rotate a principal's credentials. The new credentials will be returned in the response. This is the only + API, aside from createPrincipal, that returns the user's credentials. This API is *not* idempotent. + responses: + 200: + description: The principal details along with the newly rotated credentials + content: + application/json: + schema: + $ref: "#/components/schemas/PrincipalWithCredentials" + 403: + description: "The caller does not have permission to rotate credentials" + 404: + description: "The principal does not exist" + + /principals/{principalName}/principal-roles: + parameters: + - name: principalName + in: path + description: The name of the target principal + required: true + schema: + type: string + minLength: 1 + maxLength: 256 + pattern: '^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$' + get: + operationId: listPrincipalRolesAssigned + description: List the roles assigned to the principal + responses: + 200: + description: List of roles assigned to this principal + content: + application/json: + schema: + $ref: "#/components/schemas/PrincipalRoles" + 403: + description: "The caller does not have permission to list roles" + 404: + description: "The principal or catalog does not exist" + + put: + operationId: assignPrincipalRole + description: Add a role to the principal + requestBody: + description: The principal role to assign + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/GrantPrincipalRoleRequest" + responses: + 201: + description: "Successful response" + 403: + description: "The caller does not have permission to add assign a role to the principal" + 404: + description: "The catalog, the principal, or the role does not exist" + + /principals/{principalName}/principal-roles/{principalRoleName}: + parameters: + - name: principalName + in: path + description: The name of the target principal + required: true + schema: + type: string + minLength: 1 + maxLength: 256 + pattern: '^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$' + - name: principalRoleName + in: path + description: The name of the role + required: true + schema: + type: string + minLength: 1 + maxLength: 256 + pattern: '^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$' + delete: + operationId: revokePrincipalRole + description: Remove a role from a catalog principal + responses: + 204: + description: "Success, no content" + 403: + description: "The caller does not have permission to remove a role from the principal" + 404: + description: "The catalog or principal does not exist" + + /principal-roles: + get: + operationId: listPrincipalRoles + description: List the principal roles + responses: + 200: + description: List of principal roles + content: + application/json: + schema: + $ref: "#/components/schemas/PrincipalRoles" + 403: + description: "The caller does not have permission to list principal roles" + 404: + description: "The catalog does not exist" + + post: + operationId: createPrincipalRole + description: Create a principal role + requestBody: + description: The principal to create + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/CreatePrincipalRoleRequest" + responses: + 201: + description: "Successful response" + 403: + description: "The caller does not have permission to add a principal role" + + /principal-roles/{principalRoleName}: + parameters: + - name: principalRoleName + in: path + description: The principal role name + required: true + schema: + type: string + minLength: 1 + maxLength: 256 + pattern: '^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$' + get: + operationId: getPrincipalRole + description: Get the principal role details + responses: + 200: + description: The requested principal role + content: + application/json: + schema: + $ref: "#/components/schemas/PrincipalRole" + 403: + description: "The caller does not have permission to get principal role details" + 404: + description: "The principal role does not exist" + + put: + operationId: updatePrincipalRole + description: Update an existing principalRole + requestBody: + description: The principalRole details to use in the update + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/UpdatePrincipalRoleRequest" + responses: + 200: + description: The updated principal role + content: + application/json: + schema: + $ref: "#/components/schemas/PrincipalRole" + 403: + description: "The caller does not have permission to update principal role details" + 404: + description: "The principal role does not exist" + 409: + description: "The entity version doesn't match the currentEntityVersion; retry after fetching latest version" + + delete: + operationId: deletePrincipalRole + description: Remove a principal role from polaris + responses: + 204: + description: "Success, no content" + 403: + description: "The caller does not have permission to delete a principal role" + 404: + description: "The principal role does not exist" + + /principal-roles/{principalRoleName}/principals: + parameters: + - name: principalRoleName + in: path + description: The principal role name + required: true + schema: + type: string + minLength: 1 + maxLength: 256 + pattern: '^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$' + get: + operationId: listAssigneePrincipalsForPrincipalRole + description: List the Principals to whom the target principal role has been assigned + responses: + 200: + description: List the Principals to whom the target principal role has been assigned + content: + application/json: + schema: + $ref: "#/components/schemas/Principals" + 403: + description: "The caller does not have permission to list principals" + 404: + description: "The principal role does not exist" + + /principal-roles/{principalRoleName}/catalog-roles/{catalogName}: + parameters: + - name: principalRoleName + in: path + description: The principal role name + required: true + schema: + type: string + minLength: 1 + maxLength: 256 + pattern: '^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$' + - name: catalogName + in: path + required: true + description: The name of the catalog where the catalogRoles reside + schema: + type: string + minLength: 1 + maxLength: 256 + pattern: '^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$' + get: + operationId: listCatalogRolesForPrincipalRole + description: Get the catalog roles mapped to the principal role + responses: + 200: + description: The list of catalog roles mapped to the principal role + content: + application/json: + schema: + $ref: "#/components/schemas/CatalogRoles" + 403: + description: "The caller does not have permission to list catalog roles" + 404: + description: "The principal role does not exist" + + put: + operationId: assignCatalogRoleToPrincipalRole + description: Assign a catalog role to a principal role + requestBody: + description: The principal to create + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/GrantCatalogRoleRequest" + responses: + 201: + description: "Successful response" + 403: + description: "The caller does not have permission to assign a catalog role" + + /principal-roles/{principalRoleName}/catalog-roles/{catalogName}/{catalogRoleName}: + parameters: + - name: principalRoleName + in: path + description: The principal role name + required: true + schema: + type: string + minLength: 1 + maxLength: 256 + pattern: '^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$' + - name: catalogName + in: path + description: The name of the catalog that contains the role to revoke + required: true + schema: + type: string + minLength: 1 + maxLength: 256 + pattern: '^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$' + - name: catalogRoleName + in: path + description: The name of the catalog role that should be revoked + required: true + schema: + type: string + minLength: 1 + maxLength: 256 + pattern: '^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$' + delete: + operationId: revokeCatalogRoleFromPrincipalRole + description: Remove a catalog role from a principal role + responses: + 204: + description: "Success, no content" + 403: + description: "The caller does not have permission to revoke a catalog role" + 404: + description: "The principal role does not exist" + + /catalogs/{catalogName}/catalog-roles: + parameters: + - name: catalogName + in: path + description: The catalog for which we are reading/updating roles + required: true + schema: + type: string + minLength: 1 + maxLength: 256 + pattern: '^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$' + get: + operationId: listCatalogRoles + description: List existing roles in the catalog + responses: + 200: + description: The list of roles that exist in this catalog + content: + application/json: + schema: + $ref: "#/components/schemas/CatalogRoles" + post: + operationId: createCatalogRole + description: Create a new role in the catalog + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/CreateCatalogRoleRequest" + responses: + 201: + description: "Successful response" + 403: + description: "The principal is not authorized to create roles" + 404: + description: "The catalog does not exist" + + /catalogs/{catalogName}/catalog-roles/{catalogRoleName}: + parameters: + - name: catalogName + in: path + description: The catalog for which we are retrieving roles + required: true + schema: + type: string + minLength: 1 + maxLength: 256 + pattern: '^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$' + - name: catalogRoleName + in: path + description: The name of the role + required: true + schema: + type: string + minLength: 1 + maxLength: 256 + pattern: '^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$' + get: + operationId: getCatalogRole + description: Get the details of an existing role + responses: + 200: + description: The specified role details + content: + application/json: + schema: + $ref: "#/components/schemas/CatalogRole" + 403: + description: "The principal is not authorized to read role data" + 404: + description: "The catalog or the role does not exist" + + put: + operationId: updateCatalogRole + description: Update an existing role in the catalog + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/UpdateCatalogRoleRequest" + responses: + 200: + description: The specified role details + content: + application/json: + schema: + $ref: "#/components/schemas/CatalogRole" + 403: + description: "The principal is not authorized to update roles" + 404: + description: "The catalog or the role does not exist" + 409: + description: "The entity version doesn't match the currentEntityVersion; retry after fetching latest version" + + delete: + operationId: deleteCatalogRole + description: Delete an existing role from the catalog. All associated grants will also be deleted + responses: + 204: + description: "Success, no content" + 403: + description: "The principal is not authorized to delete roles" + 404: + description: "The catalog or the role does not exist" + + /catalogs/{catalogName}/catalog-roles/{catalogRoleName}/principal-roles: + parameters: + - name: catalogName + in: path + required: true + description: The name of the catalog where the catalog role resides + schema: + type: string + minLength: 1 + maxLength: 256 + pattern: '^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$' + - name: catalogRoleName + in: path + required: true + description: The name of the catalog role + schema: + type: string + minLength: 1 + maxLength: 256 + pattern: '^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$' + get: + operationId: listAssigneePrincipalRolesForCatalogRole + description: List the PrincipalRoles to which the target catalog role has been assigned + responses: + 200: + description: List the PrincipalRoles to which the target catalog role has been assigned + content: + application/json: + schema: + $ref: "#/components/schemas/PrincipalRoles" + 403: + description: "The caller does not have permission to list principal roles" + 404: + description: "The catalog or catalog role does not exist" + + /catalogs/{catalogName}/catalog-roles/{catalogRoleName}/grants: + parameters: + - name: catalogName + in: path + required: true + description: The name of the catalog where the role will receive the grant + schema: + type: string + minLength: 1 + maxLength: 256 + pattern: '^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$' + - name: catalogRoleName + in: path + required: true + description: The name of the role receiving the grant (must exist) + schema: + type: string + minLength: 1 + maxLength: 256 + pattern: '^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$' + get: + operationId: listGrantsForCatalogRole + description: List the grants the catalog role holds + responses: + 200: + description: List of all grants given to the role in this catalog + content: + application/json: + schema: + $ref: "#/components/schemas/GrantResources" + put: + operationId: addGrantToCatalogRole + description: Add a new grant to the catalog role + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/AddGrantRequest" + responses: + 201: + description: "Successful response" + 403: + description: "The principal is not authorized to create grants" + 404: + description: "The catalog or the role does not exist" + post: + operationId: revokeGrantFromCatalogRole + description: + Delete a specific grant from the role. This may be a subset or a superset of the grants the role has. In case of + a subset, the role will retain the grants not specified. If the `cascade` parameter is true, grant revocation + will have a cascading effect - that is, if a principal has specific grants on a subresource, and grants are revoked + on a parent resource, the grants present on the subresource will be revoked as well. By default, this behavior + is disabled and grant revocation only affects the specified resource. + parameters: + - name: cascade + in: query + schema: + type: boolean + default: false + description: If true, the grant revocation cascades to all subresources. + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/RevokeGrantRequest" + responses: + 201: + description: "Successful response" + 403: + description: "The principal is not authorized to create grants" + 404: + description: "The catalog or the role does not exist" + +components: + securitySchemes: + OAuth2: + type: oauth2 + description: Uses OAuth 2 with client credentials flow + flows: + implicit: + authorizationUrl: "{scheme}://{host}/api/v1/oauth/tokens" + scopes: {} + + schemas: + Catalogs: + type: object + description: A list of Catalog objects + properties: + catalogs: + type: array + items: + $ref: "#/components/schemas/Catalog" + required: + - catalogs + + CreateCatalogRequest: + type: object + description: Request to create a new catalog + properties: + catalog: + $ref: "#/components/schemas/Catalog" + required: + - catalog + + Catalog: + type: object + description: A catalog object. A catalog may be internal or external. Internal catalogs are managed entirely by + an external catalog interface. Third party catalogs may be other Iceberg REST implementations or other services + with their own proprietary APIs + properties: + type: + type: string + enum: + - INTERNAL + - EXTERNAL + description: the type of catalog - internal or external + default: INTERNAL + name: + type: string + minLength: 1 + maxLength: 256 + pattern: '^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$' + description: The name of the catalog + properties: + type: object + properties: + default-base-location: + type: string + additionalProperties: + type: string + required: + - default-base-location + createTimestamp: + type: integer + format: "int64" + description: The creation time represented as unix epoch timestamp in milliseconds + lastUpdateTimestamp: + type: integer + format: "int64" + description: The last update time represented as unix epoch timestamp in milliseconds + entityVersion: + type: integer + description: The version of the catalog object used to determine if the catalog metadata has changed + storageConfigInfo: + $ref: "#/components/schemas/StorageConfigInfo" + required: + - name + - type + - storageConfigInfo + - properties + discriminator: + propertyName: type + mapping: + INTERNAL: "#/components/schemas/PolarisCatalog" + EXTERNAL: "#/components/schemas/ExternalCatalog" + + + PolarisCatalog: + type: object + allOf: + - $ref: "#/components/schemas/Catalog" + description: The base catalog type - this contains all the fields necessary to construct an INTERNAL catalog + + ExternalCatalog: + description: An externally managed catalog + type: object + allOf: + - $ref: "#/components/schemas/Catalog" + - type: object + properties: + remoteUrl: + type: string + description: URL to the remote catalog API + + StorageConfigInfo: + type: object + description: A storage configuration used by catalogs + properties: + storageType: + type: string + enum: + - S3 + - GCS + - AZURE + - FILE + description: The cloud provider type this storage is built on. FILE is supported for testing purposes only + allowedLocations: + type: array + items: + type: string + example: "For AWS [s3://bucketname/prefix/], for AZURE [abfss://container@storageaccount.blob.core.windows.net/prefix/], for GCP [gs://bucketname/prefix/]" + required: + - storageType + discriminator: + propertyName: storageType + mapping: + S3: "#/components/schemas/AwsStorageConfigInfo" + AZURE: "#/components/schemas/AzureStorageConfigInfo" + GCS: "#/components/schemas/GcpStorageConfigInfo" + FILE: "#/components/schemas/FileStorageConfigInfo" + + AwsStorageConfigInfo: + type: object + description: aws storage configuration info + allOf: + - $ref: '#/components/schemas/StorageConfigInfo' + properties: + roleArn: + type: string + description: the aws role arn that grants privileges on the S3 buckets + example: "arn:aws:iam::123456789001:principal/abc1-b-self1234" + externalId: + type: string + description: an optional external id used to establish a trust relationship with AWS in the trust policy + userArn: + type: string + description: the aws user arn used to assume the aws role + example: "arn:aws:iam::123456789001:user/abc1-b-self1234" + required: + - roleArn + + AzureStorageConfigInfo: + type: object + description: azure storage configuration info + allOf: + - $ref: '#/components/schemas/StorageConfigInfo' + properties: + tenantId: + type: string + description: the tenant id that the storage accounts belong to + multiTenantAppName: + type: string + description: the name of the azure client application + consentUrl: + type: string + description: URL to the Azure permissions request page + required: + - tenantId + + GcpStorageConfigInfo: + type: object + description: gcp storage configuration info + allOf: + - $ref: '#/components/schemas/StorageConfigInfo' + properties: + gcsServiceAccount: + type: string + description: a Google cloud storage service account + + FileStorageConfigInfo: + type: object + description: gcp storage configuration info + allOf: + - $ref: '#/components/schemas/StorageConfigInfo' + + UpdateCatalogRequest: + description: Updates to apply to a Catalog + type: object + properties: + currentEntityVersion: + type: integer + description: The version of the object onto which this update is applied; if the object changed, the update will fail and the caller should retry after fetching the latest version. + properties: + type: object + additionalProperties: + type: string + storageConfigInfo: + $ref: "#/components/schemas/StorageConfigInfo" + + Principals: + description: A list of Principals + type: object + properties: + principals: + type: array + items: + $ref: "#/components/schemas/Principal" + required: + - principals + + PrincipalWithCredentials: + description: A user with its client id and secret. This type is returned when a new principal is created or when its + credentials are rotated + type: object + properties: + principal: + $ref: "#/components/schemas/Principal" + credentials: + type: object + properties: + clientId: + type: string + clientSecret: + type: string + format: password + required: + - principal + - credentials + + CreatePrincipalRequest: + type: object + properties: + principal: + $ref: '#/components/schemas/Principal' + credentialRotationRequired: + type: boolean + description: If true, the initial credentials can only be used to call rotateCredentials + + Principal: + description: A Polaris principal. + type: object + properties: + name: + type: string + minLength: 1 + maxLength: 256 + pattern: '^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$' + clientId: + type: string + description: The output-only OAuth clientId associated with this principal if applicable + properties: + type: object + additionalProperties: + type: string + createTimestamp: + type: integer + format: "int64" + lastUpdateTimestamp: + type: integer + format: "int64" + entityVersion: + type: integer + description: The version of the principal object used to determine if the principal metadata has changed + required: + - name + + UpdatePrincipalRequest: + description: Updates to apply to a Principal + type: object + properties: + currentEntityVersion: + type: integer + description: The version of the object onto which this update is applied; if the object changed, the update will fail and the caller should retry after fetching the latest version. + properties: + type: object + additionalProperties: + type: string + required: + - currentEntityVersion + - properties + + PrincipalRoles: + type: object + properties: + roles: + type: array + items: + $ref: "#/components/schemas/PrincipalRole" + required: + - roles + + GrantPrincipalRoleRequest: + type: object + properties: + principalRole: + $ref: '#/components/schemas/PrincipalRole' + + CreatePrincipalRoleRequest: + type: object + properties: + principalRole: + $ref: '#/components/schemas/PrincipalRole' + + PrincipalRole: + type: object + properties: + name: + type: string + minLength: 1 + maxLength: 256 + pattern: '^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$' + description: The name of the role + properties: + type: object + additionalProperties: + type: string + createTimestamp: + type: integer + format: "int64" + lastUpdateTimestamp: + type: integer + format: "int64" + entityVersion: + type: integer + description: The version of the principal role object used to determine if the principal role metadata has changed + required: + - name + + UpdatePrincipalRoleRequest: + description: Updates to apply to a Principal Role + type: object + properties: + currentEntityVersion: + type: integer + description: The version of the object onto which this update is applied; if the object changed, the update will fail and the caller should retry after fetching the latest version. + properties: + type: object + additionalProperties: + type: string + required: + - currentEntityVersion + - properties + + CatalogRoles: + type: object + properties: + roles: + type: array + items: + $ref: "#/components/schemas/CatalogRole" + description: The list of catalog roles + required: + - roles + + GrantCatalogRoleRequest: + type: object + properties: + catalogRole: + $ref: '#/components/schemas/CatalogRole' + + CreateCatalogRoleRequest: + type: object + properties: + catalogRole: + $ref: '#/components/schemas/CatalogRole' + + CatalogRole: + type: object + properties: + name: + type: string + minLength: 1 + maxLength: 256 + pattern: '^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$' + description: The name of the role + properties: + type: object + additionalProperties: + type: string + createTimestamp: + type: integer + format: "int64" + lastUpdateTimestamp: + type: integer + format: "int64" + entityVersion: + type: integer + description: The version of the catalog role object used to determine if the catalog role metadata has changed + required: + - name + + UpdateCatalogRoleRequest: + description: Updates to apply to a Catalog Role + type: object + properties: + currentEntityVersion: + type: integer + description: The version of the object onto which this update is applied; if the object changed, the update will fail and the caller should retry after fetching the latest version. + properties: + type: object + additionalProperties: + type: string + required: + - currentEntityVersion + - properties + + ViewPrivilege: + type: string + enum: + - CATALOG_MANAGE_ACCESS + - VIEW_CREATE + - VIEW_DROP + - VIEW_LIST + - VIEW_READ_PROPERTIES + - VIEW_WRITE_PROPERTIES + - VIEW_FULL_METADATA + + TablePrivilege: + type: string + enum: + - CATALOG_MANAGE_ACCESS + - TABLE_DROP + - TABLE_LIST + - TABLE_READ_PROPERTIES + - VIEW_READ_PROPERTIES + - TABLE_WRITE_PROPERTIES + - TABLE_READ_DATA + - TABLE_WRITE_DATA + - TABLE_FULL_METADATA + + NamespacePrivilege: + type: string + enum: + - CATALOG_MANAGE_ACCESS + - CATALOG_MANAGE_CONTENT + - CATALOG_MANAGE_METADATA + - NAMESPACE_CREATE + - TABLE_CREATE + - VIEW_CREATE + - NAMESPACE_DROP + - TABLE_DROP + - VIEW_DROP + - NAMESPACE_LIST + - TABLE_LIST + - VIEW_LIST + - NAMESPACE_READ_PROPERTIES + - TABLE_READ_PROPERTIES + - VIEW_READ_PROPERTIES + - NAMESPACE_WRITE_PROPERTIES + - TABLE_WRITE_PROPERTIES + - VIEW_WRITE_PROPERTIES + - TABLE_READ_DATA + - TABLE_WRITE_DATA + - NAMESPACE_FULL_METADATA + - TABLE_FULL_METADATA + - VIEW_FULL_METADATA + + CatalogPrivilege: + type: string + enum: + - CATALOG_MANAGE_ACCESS + - CATALOG_MANAGE_CONTENT + - CATALOG_MANAGE_METADATA + - CATALOG_READ_PROPERTIES + - CATALOG_WRITE_PROPERTIES + - NAMESPACE_CREATE + - TABLE_CREATE + - VIEW_CREATE + - NAMESPACE_DROP + - TABLE_DROP + - VIEW_DROP + - NAMESPACE_LIST + - TABLE_LIST + - VIEW_LIST + - NAMESPACE_READ_PROPERTIES + - TABLE_READ_PROPERTIES + - VIEW_READ_PROPERTIES + - NAMESPACE_WRITE_PROPERTIES + - TABLE_WRITE_PROPERTIES + - VIEW_WRITE_PROPERTIES + - TABLE_READ_DATA + - TABLE_WRITE_DATA + - NAMESPACE_FULL_METADATA + - TABLE_FULL_METADATA + - VIEW_FULL_METADATA + + AddGrantRequest: + type: object + properties: + grant: + $ref: '#/components/schemas/GrantResource' + + RevokeGrantRequest: + type: object + properties: + grant: + $ref: '#/components/schemas/GrantResource' + + ViewGrant: + allOf: + - $ref: '#/components/schemas/GrantResource' + - type: object + properties: + namespace: + type: array + items: + type: string + viewName: + type: string + minLength: 1 + maxLength: 256 + privilege: + $ref: '#/components/schemas/ViewPrivilege' + required: + - namespace + - viewName + - privilege + + TableGrant: + allOf: + - $ref: '#/components/schemas/GrantResource' + - type: object + properties: + namespace: + type: array + items: + type: string + tableName: + type: string + minLength: 1 + maxLength: 256 + privilege: + $ref: '#/components/schemas/TablePrivilege' + required: + - namespace + - tableName + - privilege + + NamespaceGrant: + allOf: + - $ref: '#/components/schemas/GrantResource' + - type: object + properties: + namespace: + type: array + items: + type: string + privilege: + $ref: '#/components/schemas/NamespacePrivilege' + required: + - namespace + - privilege + + + CatalogGrant: + allOf: + - $ref: '#/components/schemas/GrantResource' + - type: object + properties: + privilege: + $ref: '#/components/schemas/CatalogPrivilege' + required: + - privilege + + GrantResource: + type: object + discriminator: + propertyName: type + mapping: + catalog: '#/components/schemas/CatalogGrant' + namespace: '#/components/schemas/NamespaceGrant' + table: '#/components/schemas/TableGrant' + view: '#/components/schemas/ViewGrant' + properties: + type: + type: string + enum: + - catalog + - namespace + - table + - view + required: + - type + + GrantResources: + type: object + properties: + grants: + type: array + items: + $ref: "#/components/schemas/GrantResource" + required: + - grants