Connectors quickstart

Create a connector to a second origin, send one path of your application to it with a rule, and check the response through your workload.

Last updated

View as Markdown Agent setup

This guide instructs you through sending your first path to a second origin with a connector.

  • Create a connector of type http that reaches a second origin over HTTPS and sends that origin’s own Host header.
  • Add a rule that points one path of your application at the connector with the Set Connector behavior.
  • Request that path through your workload and get the answer of the second origin.

Four parts make the chain, listed in the order this guide uses them:

  1. The connector holds the address of the second origin, the Host header it sends, and the protocol it uses to connect.
  2. The rule on your application matches one path in the request phase. Its Set Connector behavior names the connector.
  3. The workload that already serves your application receives the request. Its deployment needs no change.
  4. The request for that path meets the rule, and the connector sends it to the second origin. Every other path still reaches the origin of your first connector.

A connector receives no traffic until a rule names it. This guide uses httpbin.org as the second origin, a public service that answers every request under /anything with a JSON copy of the request it received. The response you verify at the end therefore shows what the connector sent. To use your own origin, replace httpbin.org with its hostname, and /anything with its path, such as /api/.

The connector this guide leaves you with is where the Products of Connectors start. Load Balancer spreads requests across up to 15 addresses of one connector. Origin Shield protects the origin with an Origin IP ACL and HMAC signing. Live Ingest takes a live stream in through a connector of type live_ingest.

The prerequisites and the three stages show the steps of one interface at a time. Select yours:

Prerequisites

  • An application served by a workload, with a rule that sends every request to a first connector. To create all three, refer to Applications quickstart.
  • The workload domain of that workload, of the form <id>.map.azionedge.net. This guide writes it as <workload-domain>.
  • curl, to request the path through your workload.
  • The Azion CLI on your machine, authorized with a personal token.
  • The ID of your application.
  • A personal token for the Authorization header.
  • The ID of your application.

Create a connector to your second origin

A connector of type http holds the address of an origin and the settings Azion uses to reach it. You create it on its own, outside any application. This connector has one address, httpbin.org, and connects to it over HTTPS only.

The Host header tells the origin which site a request is for. By default, a connector sends the host the client requested, which is your workload domain. This connector sends httpbin.org instead, so the origin receives its own name. For more information, refer to Host header.

The connector keeps the path of each request as the client sent it. To add a directory of the origin in front of every path, refer to Path prefix. To serve the objects of a bucket instead of an HTTP origin, refer to Use a bucket as an application origin.

To create the connector with the Azion CLI, put it in a JSON file first. Save this body as connector.json:

JSON
01{
02 "name": "my-connector",
03 "active": true,
04 "type": "http",
05 "attributes": {
06 "addresses": [{ "address": "httpbin.org" }],
07 "connection_options": {
08 "transport_policy": "force_https",
09 "host": "httpbin.org"
10 }
11 }
12}

addresses lists the origin servers, and connection_options.host is the Host header the connector sends. force_https makes every connection to the origin use HTTPS.

Create the connector from the file. The command needs --type even though the file names the type:

azion create connector --type http --file connector.json

The output carries the ID of the new connector:

Created Connector with ID <connector-id>

Read the connector back in JSON. Replace <connector-id> with the ID from the previous command:

azion describe connector --connector-id <connector-id> --format json

This excerpt of the output shows the connection options, with a value for every option the file left out:

JSON
01{
02 "active": true,
03 "attributes": {
04 "addresses": [
05 {
06 "active": true,
07 "address": "httpbin.org",
08 "http_port": 80,
09 "https_port": 443,
10 "modules": null
11 }
12 ],
13 "connection_options": {
14 "dns_resolution": "both",
15 "following_redirect": false,
16 "host": "httpbin.org",
17 "http_version_policy": "http1_1",
18 "path_prefix": "",
19 "real_ip_header": "X-Real-IP",
20 "real_port_header": "X-Real-PORT",
21 "transport_policy": "force_https"
22 },
23 …
24 },
25 …
26 "id": <connector-id>,
27 …
28 "name": "my-connector",
29 …
30 "type": "http",
31 …
32}

path_prefix is empty, so the path reaches the origin unchanged. Record the id: the rule passes it as <connector-id>. The connector exists in your account.

To create the connector with the API, send a POST request to the connectors endpoint. Replace [TOKEN VALUE] with your personal token:

Shell
01curl --request POST \
02 --url https://api.azion.com/v4/workspace/connectors \
03 --header 'Accept: application/json' \
04 --header 'Authorization: Token [TOKEN VALUE]' \
05 --header 'Content-Type: application/json' \
06 --data {
07 "name": "my-connector",
08 "type": "http",
09 "attributes": {
10 "addresses": [{ "address": "httpbin.org" }],
11 "connection_options": {
12 "transport_policy": "force_https",
13 "host": "httpbin.org"
14 }
15 }
16}

addresses lists the origin servers, and connection_options.host is the Host header the connector sends. The API answers with 202. This excerpt of the response shows the connector, with a value for every setting the request left out:

JSON
01{
02 "state": "pending",
03 "data": {
04 …
05 "id": <connector-id>,
06 "name": "my-connector",
07 …
08 "active": true,
09 "product_version": "1.0",
10 "type": "http",
11 "attributes": {
12 "addresses": [
13 {
14 "active": true,
15 "address": "httpbin.org",
16 "http_port": 80,
17 "https_port": 443,
18 "modules": null
19 }
20 ],
21 "connection_options": {
22 "dns_resolution": "both",
23 "transport_policy": "force_https",
24 "http_version_policy": "http1_1",
25 "host": "httpbin.org",
26 "path_prefix": "",
27 "following_redirect": false,
28 "real_ip_header": "X-Real-IP",
29 "real_port_header": "X-Real-PORT"
30 },
31 "modules": {
32 "load_balancer": { "enabled": false, "config": null },
33 "origin_shield": { "enabled": false, "config": null }
34 }
35 },
36 …
37 }
38}

path_prefix is empty, so the path reaches the origin unchanged. Record the id: the rule passes it as <connector-id>. The connector exists in your account.

To create the connector in Azion Console:

Open the Connectors page

Access Azion Console > Connectors.

Start a new connector

The Create Connector page opens.

Name the connector

In General, enter my-connector as the Name.

Select the HTTP type

In Connector Type, select HTTP.

Enter the address of the second origin

Under Address Management, enter httpbin.org in Address, without a protocol or a port.

Send the origin's own name in the Host header

In Host, enter httpbin.org.

Connect to the origin over HTTPS only

In Transport Protocol Policy, select Force HTTPS.

Select Create

The connector exists in your account, and the rule you add to your application selects it.

Send a path to the connector

A rule in Rules Engine for Applications pairs criteria with behaviors. This rule runs in the request phase of your application. Its criterion, ${uri} starting with /anything, matches every request under that path. Its behavior, Set Connector, sends each matching request to the new connector. For more information, refer to Set Connector.

The rule from the Applications quickstart matches every path, /anything included. When several matching rules carry Set Connector, only the last one runs. Keep this rule after the catch-all rule, so it decides the connector for /anything. In the API, a new rule goes after the rules the application already has: the second rule of an application is stored with order set to 1.

To create the rule with the Azion CLI, keep the rule in a file: on a command line, the shell would expand ${uri}. Save this body as rule.json, and replace <connector-id> with the ID of the new connector:

JSON
01{
02 "name": "send-path-to-connector",
03 "active": true,
04 "criteria": [
05 [
06 {
07 "variable": "${uri}",
08 "conditional": "if",
09 "operator": "starts_with",
10 "argument": "/anything"
11 }
12 ]
13 ],
14 "behaviors": [
15 {
16 "type": "set_connector",
17 "attributes": { "value": <connector-id> }
18 }
19 ]
20}

Create the rule in the request phase of your application. Replace <application-id> with the ID of your application:

azion create rules-engine --application-id <application-id> --phase request --file rule.json

The output carries the ID of the new rule:

Created Rules Engine with ID <rule-id>

The rule is active on your application, and it sends every request under /anything to the connector.

To create the rule with the API, keep the request body in a file: on a command line, the shell would expand ${uri}. Save this body as rule.json, and replace <connector-id> with the ID of the new connector:

JSON
01{
02 "name": "send-path-to-connector",
03 "active": true,
04 "criteria": [
05 [
06 {
07 "variable": "${uri}",
08 "conditional": "if",
09 "operator": "starts_with",
10 "argument": "/anything"
11 }
12 ]
13 ],
14 "behaviors": [
15 {
16 "type": "set_connector",
17 "attributes": { "value": <connector-id> }
18 }
19 ]
20}

Send a POST request to the request-phase rules of your application. Replace <application-id> with the ID of your application:

Shell
01curl --request POST \
02 --url https://api.azion.com/v4/workspace/applications/<application-id>/request_rules \
03 --header 'Accept: application/json' \
04 --header 'Authorization: Token [TOKEN VALUE]' \
05 --header 'Content-Type: application/json' \
06 --data @rule.json

The API answers with 202 and "state": "pending", and the response returns the stored rule with its id and its order. The rule is active on your application, and it sends every request under /anything to the connector.

To create the rule in Azion Console:

Open the application

Access Azion Console > Applications, and select the application from the Applications quickstart.

Select the Rules Engine tab
Select + Rule
Name the rule

In General, enter send-path-to-connector as the Name.

Select the request phase

In Phase, select Request Phase. A rule’s phase cannot change after you create the rule.

Set the criterion

Under Criteria, select the variable ${uri} and the operator starts_with, and enter /anything as the argument.

Select the Set Connector behavior

Under Behaviors, select Set Connector.

Select your connector

In Connector, select my-connector, the connector you created for the second origin.

Select Save

The rule appears in the Rules Engine tab, under the Request heading.

Verify the response

The check is the same whichever interface created the connector and the rule. In the command, replace <workload-domain> with the workload domain of your workload.

A new connector and a new rule take several minutes to reach Azion’s distributed infrastructure, and data centers apply them at different times. Until then, a request for /anything can still reach the origin of your first connector. Repeat the request until the second origin answers. For more information, refer to Propagation.

Send a request for the path the rule matches:

curl -s https://<workload-domain>/anything

httpbin.org answers with a JSON copy of the request it received. This excerpt keeps the Host header and the URL:

JSON
01{
02 …
03 "headers": {
04 …
05 "Host": "httpbin.org",
06 …
07 },
08 …
09 "url": "https://httpbin.org/anything"
10}

Host is httpbin.org, the value the connector sends, not your workload domain. url shows that the path reached the origin unchanged. A request for any other path, such as /, still reaches the origin of your first connector. Your application sends one path to a second origin through its own connector.

Next steps

Load Balancer quickstartEnable Load Balancer on the connector, add a second address, and spread requests across both.Origin IP ACL and HMACEnable Origin Shield on the connector to allow only Azion's addresses at your origin and sign requests with HMAC.Ingestion and deliveryHow a connector of type live_ingest takes a live stream in for delivery.Connector settingsEvery field of a connector, with its type, default, allowed values, and the errors the API returns.