Creating a catalog

Written by

Updated at July 24, 2026

If you have a project, you can create a Iceberg REST Catalog catalog in it.

Before you create a catalog, make sure the bucket referenced by the spec.stacklandStorage.bucketRef parameter already exists. To create a bucket, follow this guide.

CLI

Management console

If the project does not exist yet, create it: kubectl create namespace <project name>.
Create the RestCatalog resource file, e.g., using the touch restcatalog.yaml command.

Open the file and paste the configuration below into it:

apiVersion: restcatalog.stackland.yandex.cloud/v1alpha1
kind: RestCatalog
metadata:
  name: analytics                    # Catalog name, which is unique within the cluster
spec:
  allowedLocations:                  # Allowed storage paths for table data (at least one)
    - "s3://analytics-bucket/wh/"
  stacklandStorage:
    bucketRef: analytics-bucket      # Link to an existing bucket (Bucket CR)
  defaultBaseLocation: "s3://analytics-bucket/wh/"   # Optional; included in allowedLocations
  defaultNamespace:                  # Optional; array of namespace segments
    - analytics
    - reporting
  properties:                        # Optional; additional catalog properties
    some-key: some-value
  declaredPrincipalRoles:            # Optional; catalog user groups
    - name: analytics-admin
  catalogRoles:                      # Optional; catalog roles with privileges
    - name: analytics-admin-all
      principalRoles:
        - analytics-admin
      catalog:                       # One of the branches: catalog, namespace, table, or view
        privileges:
          - CATALOG_MANAGE_CONTENT

Apply the manifest: kubectl apply -f restcatalog.yaml -n <project name>. Optionally, you can specify the project name in the metadata.namespace resource property and skip it in the command.

If you have not opened a project yet, select one.
In the left-hand menu, select Iceberg REST Catalog.
In the Catalogs tab, click Create catalog.
Fill out the fields as follows:
- Name: Catalog name. Once created, the name never changes.
- Bucket name: Select an existing bucket from the list or create a new one.
- Allowed storage paths: Specify at least one path in s3://<bucket name>/... format. Add more than one path if needed.
- Default base path: Select one of the allowed paths or leave the field empty.
- Default namespace: Specify path segments if needed.
- Additional parameters: Specify key-value pairs if needed.
Under User groups, add the names of the catalog's user groups.
Under Catalog roles, add roles if needed. For each role, specify the name, user groups, scope (Catalog, Namespace, Table, or Visualization), and privileges.
Click Create.

Creating a catalog

Was the article helpful?