> ## Documentation Index
> Fetch the complete documentation index at: https://docs.formal.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Hostname and TLS Configuration

> How to setup hostnames and TLS for your Connectors

The Formal Connector supports encrypted communication using TLS. You can ensure that communications between clients and the Connector are encrypted and ensure that communications between the Connector and Resources are encrypted.

```mermaid theme={null}
sequenceDiagram
    participant Client as Client
    participant Connector as Connector
    participant Resource as Resource

    Note over Client, Connector: TLS Encrypted Connection
    Client->>Connector: Request

    Note over Connector, Resource: TLS Encrypted Connection
    Connector->>Resource: Request
    Resource-->>Connector: Response

    Connector-->>Client: Response
```

## TLS between the Connector and Resources

You can configure TLS settings between the Connector and resources on an individual resource level via our APIs, Terraform, or the Formal console:

<img src="https://mintcdn.com/formal/fJsHlx-X_b_ATHwb/assets/images/resource_tls_configuration.png?fit=max&auto=format&n=fJsHlx-X_b_ATHwb&q=85&s=a7db2361983accfd5077a6c5cf1fe633" width="765" height="165" data-path="assets/images/resource_tls_configuration.png" />

TLS settings for connections between the Connector and Resources are configured per-resource either via the UI or Terraform. The TLS configuration can be set to one of the following options: `disable`, `insecure-skip-verify`, `insecure-verify-ca-only` (verifies certificate chain but not hostname), or `verify-full`.

## Resource Hostnames

For resources with multiple instances or endpoints, you can register specific hostnames to distinguish between different access patterns. For example, a Postgres cluster might have separate reader and writer instances, each requiring different connection parameters.

### Configure Resource Hostnames

Use the `formal_resource_hostname` resource to register specific hostnames for your resources:

```hcl theme={null}
# Reader instance hostname
resource "formal_resource_hostname" "postgres_reader" {
  name       = "postgres-reader"
  hostname   = "postgres-reader.example.com"
  resource_id = var.postgres_resource_id
}

# Writer instance hostname
resource "formal_resource_hostname" "postgres_writer" {
  name       = "postgres-writer"
  hostname   = "postgres-writer.example.com"
  resource_id = var.postgres_resource_id
}
```

### Resource Schema

#### Required Arguments

* **`hostname`** (String) - The hostname for this Resource hostname
* **`name`** (String) - The name of this Resource Hostname
* **`resource_id`** (String) - The ID of the Resource this hostname is linked to

#### Optional Arguments

* **`termination_protection`** (Boolean) - If set to true, this resource hostname cannot be deleted
* **`timeouts`** (Block, Optional) - Timeout configuration for the resource

#### Read-Only Attributes

* **`id`** (String) - The ID of this Resource Hostname

### Example: Multi-Instance Database Setup

```hcl theme={null}
# Main Postgres resource
resource "formal_resource" "postgres_cluster" {
  name = "postgres-cluster"
  # ... other configuration
}

# Reader hostname
resource "formal_resource_hostname" "reader" {
  name       = "postgres-reader"
  hostname   = "postgres-reader.internal.company.com"
  resource_id = formal_resource.postgres_cluster.id
}

# Writer hostname
resource "formal_resource_hostname" "writer" {
  name       = "postgres-writer"
  hostname   = "postgres-writer.internal.company.com"
  resource_id = formal_resource.postgres_cluster.id
}
```

**Verify:**

```bash theme={null}
terraform plan
terraform apply
```

### Resource Hostname Specification

When connecting through the Formal Connector, you can target specific resource hostnames using the database name parameter. Use the format `database@resource-name@hostname-name` to specify both the resource and its specific hostname. Alternatively, you can use `database@resource-name` and include `formal_resource_hostname_name=hostname-name` in your connection parameters. This feature enables precise routing to specific database instances when you have multiple hostnames configured for a single resource, providing flexibility in managing multi-host database deployments.

**Example:**

```bash theme={null}
psql "host=localhost port=4002 user=idp:formal:human:user@example.com password=TOKEN dbname=mydb@my-resource@primary-hostname"
```