Connector settings

A connector is the object that holds where and how an application reaches an origin, the server that holds your content. Its type, http, storage, or live_ingest, sets which settings the connector carries. Azion Console and the Azion API write the same object, so each table on this page names the Console label beside the API field. API fields are written as paths inside the request body, such as attributes.connection_options.host.

Connector object

The JSON body below is a complete connector of type http with one address, every connection option at its default except transport_policy and host, and Load Balancer and Origin Shield off:

The API path is /v4/workspace/connectors, and one connector is /v4/workspace/connectors/{connector_id}. A POST that creates a connector answers 202 with "state": "pending" and the full object, defaults included. A PATCH merges the keys you send into the stored object. A PUT replaces it: a PUT without connection_options resets every connection option to its default. For every operation, refer to the Azion API.

The Azion CLI takes the same JSON body from a file: azion create connector --type http --file my-connector.json prints Created Connector with ID <connector-id>.

A change to a connector takes effect without a new deployment. It reaches Azion’s distributed infrastructure in several minutes, and data centers apply it at different times. An application sends requests to a connector through a rule with the Set Connector behavior. To write that rule, refer to Rules Engine for Applications.

General

The general fields name the connector and set its type. The API requires name, type, and attributes on every connector.

A connector of type http takes the fields in Addresses, Connection options, Load Balancer, and Origin Shield. A connector of type storage takes the fields in Storage, and a connector of type live_ingest takes the field in Live Ingest.

Addresses

The addresses of a connector of type http are the origin servers it connects to. Each item of attributes.addresses holds one address with its ports, its state, and its role in load balancing. The Console section Address Management writes them.

A connector holds one address unless Load Balancer is on. Two addresses with Load Balancer off are refused with 28004. With Load Balancer on, a connector holds up to 15 addresses, and a 16th is refused with 28011. For every bound in one place, refer to Connectors limits.

An address with a protocol or a port, such as https://origin.example.com or origin.example.com:443, is refused with 28001. The Console shows Address must be a valid IPv4, IPv6, or hostname, without protocol or port. Set the ports in HTTP Port and HTTPS Port, and a path in path_prefix.

An address reads back "modules": null until you send its Load Balancer fields. An address sent with only weight reads back server_role as primary, and one sent with only server_role reads back weight as 1. A backup address is refused under the IP Hash method with 28005. The Console shows Backup role is not available when the load balancing method is IP Hash. and Backup role is not supported with IP Hash. Change this address to Primary or select another method. A weight outside the range shows Weight must be between 1 and 100 in the Console.

Connection options

The connection options of a connector of type http set how the connector talks to its addresses: the Host header, the path, the protocol, the IP version, and the headers that carry the client’s address. They sit in attributes.connection_options.

The host value decides which name the origin sees. For example, with the default ${host}, a client that requests www.example.com makes the connector send Host: www.example.com. With "host": "origin.example.com", the connector sends Host: origin.example.com for every request. An origin that routes requests by name may not answer to the client’s host, so send the origin’s own name as a literal value. The Console validates Host with Host must be a valid hostname, IP address, or variable.

The path_prefix value goes in front of the path the client requested. With /anything, a request for /get reaches the origin as /anything/get. For Path, the Console reads “Use ’/’ for the root path.” and validates the field with Path must start with a forward slash (/).

By default, the origin receives the client IP address in X-Real-IP and the client port in X-Real-PORT. Renaming real_ip_header changes the header name: with X-Client-Real-IP, the origin receives X-Client-Real-IP and no X-Real-IP. Some origins drop X-Real-IP themselves. To add the client IP to a header with a rule instead, refer to Send the client IP to the origin in a header.

Load Balancer

Load Balancer distributes requests across the addresses of a connector of type http. In the Console, the Load Balancer switch in the Modules section turns it on, and the Method, Max Retries, Connection Timeout, and Read/Write Timeout fields appear. In the API, the fields sit in attributes.modules.load_balancer.

With enabled set to true, config must carry at least one key, or the API refuses the request with 28014. A key you leave out takes the API default. For example, "config": {"method": "round_robin"} reads back with max_retries 0, connection_timeout 60, and read_write_timeout 120. When you turn on Load Balancer in the Console, the form fills in Round Robin, 3, 30, and 60 instead.

The retries and the two timeouts exist only with Load Balancer on. A connector without Load Balancer has no configurable timeout. For the timeouts that apply then, refer to How Connectors works. For how each method chooses an address, refer to Balancing methods.

Origin Shield

Origin Shield protects the origin of a connector of type http in two ways. Origin IP ACL lets your origin accept only Azion’s published addresses, and HMAC signs each request the connector sends to the origin. In the API, the fields sit in attributes.modules.origin_shield.

With enabled set to true, config must carry at least one key, and with hmac.enabled set to true, hmac.config must be present. Otherwise the API refuses the request with 28014. Turning HMAC off removes the stored credentials, so you enter them again when you turn it back on.

The HMAC credentials belong to an account at the object storage provider that holds the private content. For example, a connector that reads a private bucket through the S3 endpoint s3.us-east-005.azionstorage.net sends region us-east-005, service s3, and a credential scoped to that bucket. With HMAC off, that endpoint answers 401. For how Origin IP ACL and HMAC protect the origin, refer to Origin IP ACL and HMAC.

Storage

A connector of type storage reads from an Object Storage bucket in your account. It carries two attributes and no addresses or connection options.

The bucket selector lists the buckets of your account, and Create Object Storage creates a bucket without leaving the form. In the API, leave prefix out to store null, and never send it empty. For example, this body creates a connector of type storage for the objects under images/:

Live Ingest

A connector of type live_ingest belongs to Live Ingest. It carries one attribute, region, and no addresses or connection options.

A request without region is refused with 10059, and a value outside the list with 10039. A bucket sent with this type is accepted and not stored. For example, this body creates a connector of type live_ingest in br-east-1:

For how Live Ingest works, refer to Ingestion and delivery.

Errors

The API refuses each request below with HTTP 400 and creates or changes nothing. The code and the message are in the response’s errors array, with a source.pointer to the field.

The Azion CLI prints the same message inside its own error. For 28000, that is Error: Failed to delete the Connector: [...].

Related resources