UnityCatalogServer — Localhost Reference Server¶

UnityCatalogServer is Unity Catalog's Localhost Reference Server.

UnityCatalogServer can be started as a command-line application using the bin/start-uc-server shell script.

$ ./bin/start-uc-server
###################################################################
#  _    _       _ _            _____      _        _              #
# | |  | |     (_) |          / ____|    | |      | |             #
# | |  | |_ __  _| |_ _   _  | |     __ _| |_ __ _| | ___   __ _  #
# | |  | | '_ \| | __| | | | | |    / _` | __/ _` | |/ _ \ / _` | #
# | |__| | | | | | |_| |_| | | |___| (_| | || (_| | | (_) | (_| | #
#  \____/|_| |_|_|\__|\__, |  \_____\__,_|\__\__,_|_|\___/ \__, | #
#                      __/ |                                __/ | #
#                     |___/                        v0.5.0  |___/  #
###################################################################

UnityCatalogServer command-line application starts the Unity Catalog API services (with the Armeria documentation service at http://localhost:8080/docs).

Launch UnityCatalogServer Command-Line Application¶

void main(
  String[] args)

main is the entry point of bin/start-uc-server shell script.

main performs the following steps in order:

1. Creates an OptionParser to parse the command-line options (args).
2. Creates a UnityCatalogServer.Builder and sets its port to the value of the --port option incremented by 1.
3. Requests the UnityCatalogServer.Builder to build a UnityCatalogServer instance
4. Prints the welcome ASCII art message.
5. Starts the UnityCatalogServer.

6. Creates a URLTranscoderVerticle bound to the following ports:

   Port	Role
   8080 or --port	Transcode port (inbound)
   8081 or --port + 1	Service port (forwarded)

7. Deploys the URLTranscoderVerticle on a non-clustered Vert.x instance.

Create UnityCatalogServer.Builder¶

UnityCatalogServer.Builder builder()

builder creates a new UnityCatalogServer.Builder.

builder is used when:

• UnityCatalogServer is launched as a command-line application

Armeria Server¶

UnityCatalogServer initializes an Armeria Server when created.

The server is started to listen to service requests when the UnityCatalogServer is requested to start. It is stopped when the UnityCatalogServer is requested to stop.

Initialize¶

Server initializeServer(
  UnityCatalogServer.Builder unityCatalogServerBuilder)

initializeServer creates an Armeria Server (Armeria) to listen on the HTTP port (of the given UnityCatalogServer.Builder) on all available network interfaces.

initializeServer creates a HibernateConfigurator (for the serverProperties).

initializeServer registers the Unity Catalog API services (based on the serverProperties) with the following auxiliary services:

1. Built-in Armeria documentation service (Armeria) under /docs path (e.g., http://localhost:8081/docs/)
2. Repositories (and initMetastoreIfNeeded)
3. UnityCatalogAuthorizer

initializeServer adds the security decorators.

initializeServer builds a newly-created Armeria Server.

Register Unity Catalog API Services¶

void addApiServices(
  ServerBuilder armeriaServerBuilder,
  UnityCatalogServer.Builder unityCatalogServerBuilder,
  ServerProperties serverProperties,
  UnityCatalogAuthorizer authorizer,
  Repositories repositories)

addApiServices prints the following INFO message to the logs:

Adding Unity Catalog API services...

addApiServices creates a CloudCredentialVendor unless defined using the given UnityCatalogServer.Builder.

addApiServices creates a StorageCredentialVendor.

addServices registers the Unity Catalog API services.

addServices prints the following INFO message to the logs while registering IcebergRestCatalogService:

Adding Iceberg services...

addServices prints the following INFO message to the logs while registering DeltaApiService:

Adding UC Delta API services...

Register Unity Catalog API Security Decorators¶

void addSecurityDecorators(
  ServerBuilder armeriaServerBuilder,
  ServerProperties serverProperties,
  UnityCatalogAuthorizer authorizer,
  Repositories repositories)

With server.authorization configuration property enabled, addSecurityDecorators prints the following INFO message to the logs:

Enabling security decorators...

addServices registers the Unity Catalog API service decorators.

Start¶

void start()

start prints out the following INFO message to the logs:

Starting Unity Catalog server...

start requests this Armeria Server to start (and listen to the defined ports). It waits until this Server is fully started up.

start prints out the following INFO message to the logs:

Unity Catalog server started.

Stop¶

void stop()

stop requests this Armeria Server to stop and waits until it is stopped.

stop prints out the following INFO message to the logs:

Unity Catalog server stopped.

Metastore¶

UnityCatalogServer runs with a single metastore only that can be created unless available already.

The summary of the single metastore is available through MetastoreService at /api/2.1/unity-catalog/ URL.

Configuration Files¶

UnityCatalogServer uses the following configuration files:

• etc/conf/server.log4j2.properties
• etc/conf/server.properties

SecurityContext¶

UnityCatalogServer creates a SecurityContext when created as follows:

This SecurityContext is used to create an AuthService.

Creating Instance¶

UnityCatalogServer takes the following to be created:

• UnityCatalogServer.Builder

While being created, UnityCatalogServer does the following:

1. Initializes the logging (using etc/conf/server.log4j2.properties configuration file).
2. Sets the default values for the port and server properties (unless set).
3. Initializes this securityContext, serverProperties and server

UnityCatalogServer is created when:

• UnityCatalogServer command-line utility is started

setDefaults¶

void setDefaults(
  UnityCatalogServer.Builder unityCatalogServerBuilder)

setDefaults sets the port and serverProperties to their default values unless defined:

Logging¶

Enable ALL logging level for io.unitycatalog.server.UnityCatalogServer logger to see what happens inside.

Add the following line to etc/conf/server.log4j2.properties:

logger.UnityCatalogServer.name = io.unitycatalog.server.UnityCatalogServer
logger.UnityCatalogServer.level = all

Refer to Logging.