> For the complete documentation index, see [llms.txt](https://v2.dataos.info/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://v2.dataos.info/references/engine-guide/spark-1/permissions-and-grants.md).

# Permissions and grants

Configure minimum Iceberg catalog and object-storage permissions for Vulcan Spark projects.

Vulcan Spark uses a DataOS Lakehouse Depot to connect to an Iceberg REST catalog and its object-storage warehouse. The catalog and storage credentials must both allow every operation performed by the project.

This page defines the minimum technical permissions for:

* A read-only Consumer-Aligned Data Product (CADP) that queries existing Iceberg tables.
* A project that materializes models in the Lakehouse.

## How Spark receives Lakehouse credentials

Attach a Lakehouse Depot to the Vulcan deployment. The DataOS Spark runtime generates the corresponding `spark.sql.catalog.<catalog-name>.*` configuration from the Depot and its Secret. Do not copy Lakehouse credentials into `sparkConf`.

Only Lakehouse Depots generate this Iceberg catalog configuration automatically. Other Spark catalogs can still be configured manually with their required connector and credentials. See [Connect Spark to catalogs](https://v2.dataos.info/references/engine-guide/spark-1/connection-options.md).

## Required credential layers

Every Lakehouse connection uses two credential layers:

| Layer                | Credential                    | Purpose                                                                                   |
| -------------------- | ----------------------------- | ----------------------------------------------------------------------------------------- |
| Iceberg REST catalog | `lh_access_token`             | Authenticates catalog requests and determines which namespaces and tables can be accessed |
| Object storage       | S3, GCS, or ABFSS credentials | Reads and writes Iceberg metadata and data files in the Lakehouse warehouse               |

Both layers must provide matching access. Catalog write permission without storage write permission, or storage write permission without catalog write permission, causes model operations to fail.

## Lakehouse Depot Secret fields

Configure the fields that match the Lakehouse storage backend:

| Secret field      | Required for         | Purpose                                         |
| ----------------- | -------------------- | ----------------------------------------------- |
| `lh_access_token` | All Lakehouse Depots | DataOS API key used by the Iceberg REST catalog |
| `aws_access_key`  | S3                   | AWS access key ID                               |
| `aws_secret_key`  | S3                   | AWS secret access key                           |
| `gcp_json_key`    | GCS                  | Base64-encoded Google Cloud service-account key |
| `az_account_name` | ABFSS                | Azure storage account name                      |
| `az_account_key`  | ABFSS                | Azure storage account key                       |

Do not place these values in model files, `config.yaml`, `deploy.yaml`, or `sparkConf`.

## Read-only CADP access

Use read-only access when the CADP queries existing Lakehouse tables and does not materialize models.

### Catalog access

Grant read access to each source namespace used by the CADP. This allows Spark to:

* List namespaces and tables.
* Load table metadata.
* Read Iceberg tables referenced by semantic queries.

Do not grant create, alter, drop, insert, update, or delete access to a read-only CADP.

### S3 access

Grant bucket discovery and object reads only for the required source paths:

```json
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "s3:GetBucketLocation",
      "Resource": "arn:aws:s3:::<LAKEHOUSE_BUCKET>"
    },
    {
      "Effect": "Allow",
      "Action": "s3:ListBucket",
      "Resource": "arn:aws:s3:::<LAKEHOUSE_BUCKET>",
      "Condition": {
        "StringLike": {
          "s3:prefix": [
            "<SOURCE_NAMESPACE>",
            "<SOURCE_NAMESPACE>/*"
          ]
        }
      }
    },
    {
      "Effect": "Allow",
      "Action": "s3:GetObject",
      "Resource": "arn:aws:s3:::<LAKEHOUSE_BUCKET>/<SOURCE_NAMESPACE>/*"
    }
  ]
}
```

## Model read/write access

Use read/write access when Vulcan materializes `FULL`, incremental, SCD Type 2, or seed models.

### Catalog access

Grant permissions by namespace:

| Namespace              | Minimum access | Purpose                                            |
| ---------------------- | -------------- | -------------------------------------------------- |
| Source namespace       | Read           | Reads source tables and metadata                   |
| Model target namespace | Read and write | Creates, replaces, alters, and writes model tables |

The target permissions must support the operations used by the selected model kinds, including table creation, replacement, schema changes, inserts, overwrites, deletes, and `MERGE INTO` where applicable.

### S3 access

Grant read-only object access to source paths and read/write/delete access to target paths:

```json
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "s3:GetBucketLocation",
      "Resource": "arn:aws:s3:::<LAKEHOUSE_BUCKET>"
    },
    {
      "Effect": "Allow",
      "Action": "s3:ListBucket",
      "Resource": "arn:aws:s3:::<LAKEHOUSE_BUCKET>",
      "Condition": {
        "StringLike": {
          "s3:prefix": [
            "<SOURCE_NAMESPACE>",
            "<SOURCE_NAMESPACE>/*",
            "<TARGET_NAMESPACE>",
            "<TARGET_NAMESPACE>/*"
          ]
        }
      }
    },
    {
      "Effect": "Allow",
      "Action": "s3:GetObject",
      "Resource": "arn:aws:s3:::<LAKEHOUSE_BUCKET>/<SOURCE_NAMESPACE>/*"
    },
    {
      "Effect": "Allow",
      "Action": [
        "s3:GetObject",
        "s3:PutObject",
        "s3:DeleteObject"
      ],
      "Resource": "arn:aws:s3:::<LAKEHOUSE_BUCKET>/<TARGET_NAMESPACE>/*"
    }
  ]
}
```

## GCS and ABFSS access

Apply the same permission boundary when the Lakehouse uses GCS or ABFSS:

| Access profile   | GCS or ABFSS requirement                                                         |
| ---------------- | -------------------------------------------------------------------------------- |
| Read-only CADP   | List the required bucket or container paths and read source objects              |
| Model read/write | Read source objects and read, create, update, and delete objects in target paths |

Configure the identity and backend-specific permissions while creating the Lakehouse and Lakehouse Depot. See [Create a Lakehouse](https://v2.dataos.info/references/resources/lakehouse/create-a-lakehouse.md).

## Attach the Lakehouse Depot

{% tabs %}
{% tab title="config.yaml" %}

```yaml
deployment:
  depots:
    - dataos://<lakehouse-depot-name>?purpose=rw
```

{% endtab %}

{% tab title="deploy.yaml" %}

```yaml
spec:
  depots:
    - dataos://<lakehouse-depot-name>?purpose=rw
```

{% endtab %}
{% endtabs %}

`purpose=rw` makes the Depot available to the Spark deployment. It does not replace catalog or object-storage permissions.

## Validate permissions

Validate each layer independently:

1. Confirm that the Depot can authenticate with the Iceberg REST catalog.
2. List the required source namespaces and tables.
3. Run a controlled read from a source table.
4. For a writable project, create and write a test table in the target namespace.
5. Remove the test table and verify that cleanup succeeds.

Do not test write access in a source namespace intended to remain read-only.

## Related

* [Connect Spark to catalogs](https://v2.dataos.info/references/engine-guide/spark-1/connection-options.md)
* [Create a Lakehouse](https://v2.dataos.info/references/resources/lakehouse/create-a-lakehouse.md)
* [Create a Lakehouse Depot](https://v2.dataos.info/references/resources/lakehouse/create-a-lakehouse-depot.md)
* [Spark materialization behavior](https://v2.dataos.info/references/engine-guide/spark-1/materialization-behaviour.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://v2.dataos.info/references/engine-guide/spark-1/permissions-and-grants.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
