diff --git a/docs/configuring-polaris-for-production.md b/docs/configuring-polaris-for-production.md new file mode 100644 index 0000000000..b4077f34d2 --- /dev/null +++ b/docs/configuring-polaris-for-production.md @@ -0,0 +1,82 @@ + + + +# Configuring Polaris for Production + +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/polaris-catalog/polaris/blob/b482617bf8cc508b37dbedf3ebc81a9408160a5e/polaris-service/src/main/java/io/polaris/service/auth/JWTRSAKeyPair.java#L24) or [symmetric](https://github.com/polaris-catalog/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/polaris-catalog/polaris/blob/8290019c10290a600e40b35ddb1e2f54bf99e120/polaris-service/src/main/java/io/polaris/service/context/CallContextResolver.java#L27) and [RealmContextResolver](https://github.com/polaris-catalog/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/polaris-catalog/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-1.0.0-all.jar bootstrap polaris-server.yml +``` + +Afterwards, Polaris can be launched normally: + +```bash +java -jar /path/to/jar/polaris-service-1.0.0-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/docs/index.html b/docs/index.html index fff27272da..8c25542041 100644 --- a/docs/index.html +++ b/docs/index.html @@ -430,7 +430,7 @@ -
Polaris Catalog Logo
API docs by Redocly
Polaris Catalog Logo
API docs by Redocly
Catalog privileges

Diagram that shows an example of how RBAC works in Polaris Catalog.

+

Configuring Polaris for Production

+ + +

Configuring Polaris for Production

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 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 or symmetric 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 and RealmContextResolver).
    • +
+

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 implementation where Polaris entities will be persisted.

+

Be sure to secure your metastore backend since it will be storing credentials and catalog metadata.

+ +

To use EclipseLink for metastore management, specify the configuration metaStoreManager.conf-file to point to an EclipseLink persistence.xml file. 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:

+
java -jar /path/to/jar/polaris-service-1.0.0-all.jar bootstrap polaris-server.yml
+
+

Afterwards, Polaris can be launched normally:

+
java -jar /path/to/jar/polaris-service-1.0.0-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.
    • +

other

listCatalogs

List all catalogs in this polaris service

Authorizations:
Polaris_Management_Service_OAuth2

Responses

Request samples

Content type
application/json
{
  • "source": {
    },
  • "destination": {
    }
}

Response samples

Content type
application/json
{
  • "error": {
    }
}