# Configuring network access for external clients

This page describes how to establish network access for external Iceberg clients connecting to Foundry's Iceberg catalog. For information on how clients authenticate with the catalog, see [Authenticating Iceberg clients](../authentication/index.md).

When connecting externally to Foundry Iceberg tables, there are two endpoints for which network access needs to be established:

* **[Foundry's Iceberg REST catalog](#iceberg-rest-catalog-network-ingress):** used to discover tables, read schemas, and request vended credentials.
* **[The underlying storage bucket](#storage-bucket-network-ingress):** used to read or write data and metadata files, via credentials vended from the catalog.

Both endpoints must be reachable from the external client's network. If either is unreachable, the client cannot read or write tables.

## Iceberg REST catalog network ingress

The Foundry Iceberg REST catalog is served from your Foundry hostname at `https://<your_foundry_hostname>/iceberg`. You can make it accessible by enabling network ingress to the overall Foundry application layer, in the same way as any Foundry API.

Follow the steps in [Foundry application: configure network ingress](../../administration/configure-ingress/index.md) to enable network access to the Foundry application layer, including the Iceberg REST catalog API.

With catalog access alone, an authenticated client can list tables and read schemas, but cannot fetch metadata or data files until you also configure storage bucket access.

## Storage bucket network ingress

To establish network ingress from your external client to the underlying Iceberg storage bucket, take the following steps:

1. [Identify the storage bucket details](#identify-the-storage-bucket-details)
2. [Configure storage bucket access](#configure-storage-bucket-access)

### Identify the storage bucket details

Iceberg namespace identifiers are dot-separated, but they appear in catalog URLs with the unit separator character (`%1F`) between levels. For example, the namespace `Namespace.Project.Folder` is encoded as `Namespace%1FProject%1FFolder` in the URL path.

To find the storage bucket that backs a given Iceberg table, query the catalog for the table's metadata and read the `location` field:

```bash
curl --silent --show-error \
  "https://<your_foundry_hostname>/iceberg/v1/namespaces/<namespace>/tables/<table>" \
  -H "Authorization: Bearer <your_token>" \
  | jq -r '.metadata.location'
```

The response is a storage URI of the form `s3://<bucket_name>/iceberg/<table_locator>`, or the equivalent for Azure Blob File System (ABFS) or Google Cloud Storage. The host portion identifies the bucket. If your enrollment uses multiple storage buckets, repeat the lookup for one table per bucket you wish to connect to.

Alternatively, you can find the same `location` value in the dataset's **Details > Metadata file** view, at the top of the displayed metadata JSON.

### Configure storage bucket access

**When using [Foundry-managed storage](../storage/index.md):** Palantir operates the underlying storage bucket and will need to allowlist the external client traffic. Contact Palantir Support to request this, and provide the following details:

* Your Foundry hostname
* The storage bucket names, identified in the previous step
* The egress IPv4 addresses or Virtual Private Cloud (VPC) endpoint identifiers of the external client

**When using [bring-your-own-bucket (BYOB) storage](../iceberg-byob/index.md):** the storage bucket resides in your own cloud account. Update the bucket or storage account network policy directly in your cloud account to allow traffic from the external client.

## Verify connectivity

Once network ingress is set up to both the Foundry Iceberg catalog and the storage location, you can validate the configuration with a lightweight, client-independent check. Take the following steps:

1. **Ask the catalog for the table's metadata and vended credentials.** First, [generate a token](../../platform-security-third-party/user-generated-tokens/index.md), then call the catalog with the `X-Iceberg-Access-Delegation: vended-credentials` header:

   ```bash
   RESPONSE=$(curl --silent --show-error \
     "https://<your_foundry_hostname>/iceberg/v1/namespaces/<namespace>/tables/<table>" \
     -H "Authorization: Bearer <your_token>" \
     -H "X-Iceberg-Access-Delegation: vended-credentials")
   ```

   The response is served entirely by the catalog and contains the full table metadata inline, plus a `config` map with short-lived storage credentials. No bucket call is required to read metadata.

2. **Pick a file path out of the metadata.** The current snapshot's `manifest-list` is a convenient choice — it lives in the bucket and is referenced directly from the metadata. Also extract the storage credentials:

   ```bash
   CURRENT_SNAPSHOT_ID=$(echo "$RESPONSE" | jq -r '.metadata["current-snapshot-id"]')
   FILE_PATH=$(echo "$RESPONSE" | jq -r --argjson id "$CURRENT_SNAPSHOT_ID" \
     '.metadata.snapshots[] | select(.["snapshot-id"] == $id) | .["manifest-list"]')

   export AWS_ACCESS_KEY_ID=$(echo "$RESPONSE" | jq -r '.config["s3.access-key-id"]')
   export AWS_SECRET_ACCESS_KEY=$(echo "$RESPONSE" | jq -r '.config["s3.secret-access-key"]')
   export AWS_SESSION_TOKEN=$(echo "$RESPONSE" | jq -r '.config["s3.session-token"]')
   ```

3. **Fetch the file from the storage bucket using the vended credentials.** For S3-backed tables:

   ```bash
   aws s3 cp "$FILE_PATH" /dev/null
   ```

If the command succeeds, the catalog vended credentials successfully and the bucket is reachable for files under this table's prefix — confirming the ingress configuration is correct. An `AccessDenied` error indicates that the source IP address or VPC endpoint is not on the bucket's allowlist.

To go further and verify a full table read (catalog + metadata + data files) using an Iceberg client, see [Verify connectivity with a bearer token](../authentication/index.md#verify-connectivity-with-a-bearer-token).

:::callout{theme="warning"}
Network allowlisting is additive to authentication. The catalog still verifies the calling principal's permissions before vending credentials, so the user who generated the token must also have read or write permission on the target table.
:::