Listeners & Routing Rules

Q: In what order are rules evaluated?

By Priority, lowest number first. The first rule whose conditions all match wins and evaluation stops; if none match, the listener's default action runs.

Q: What condition fields can I route on?

path-pattern, host-header, http-header, http-request-method, query-string, and source-ip.

Q: How do I redirect HTTP to HTTPS?

Give the port 80 listener a default redirect action with RedirectConfig set to Protocol: "HTTPS", Port: "443", and StatusCode: "HTTP_301".

Q: Can the ALB return a response without a backend?

Yes. A fixed-response action returns a canned status code, content type, and body directly from the load balancer - useful for maintenance pages or blocking paths.

Q: Does path-pattern support regular expressions?

No. It supports only * and ? wildcards and matches the URL path (not the query string). Use a query-string condition to match query parameters.

Q: How do I reorder existing rules?

Call SetRulePriorities with the rule ARNs and their new priority numbers. Priorities must stay unique per listener.

A listener is where an Application Load Balancer accepts connections, and routing rules are how it decides where each request goes. Together they turn one ALB and one DNS name into a router that can send /api to one service, api.example.com to another, and everything else to a default.

This page creates a listener, layers prioritized rules on top of it, and shows the action types beyond a plain forward - redirects and fixed responses. Rules are a Layer 7 feature, so everything here is ALB-only; an NLB forwards by port with no content rules.

Recipe

Start with the listener. Its DefaultActions is the fallback that runs when no rule matches - here, forward everything to a web-tg target group on port 80.

# --- Python (boto3) ---
import boto3
 
elbv2 = boto3.client("elbv2", region_name="us-east-1")
resp = elbv2.create_listener(
    LoadBalancerArn="arn:...:loadbalancer/app/web-alb/abc",
    Protocol="HTTP",
    Port=80,
    DefaultActions=[{"Type": "forward", "TargetGroupArn": "arn:...:targetgroup/web-tg/111"}],
)
listener_arn = resp["Listeners"][0]["ListenerArn"]

// --- TypeScript (AWS SDK v3) ---
import { ElasticLoadBalancingV2Client, CreateListenerCommand } from "@aws-sdk/client-elastic-load-balancing-v2";
 
const elbv2 = new ElasticLoadBalancingV2Client({ region: "us-east-1" });
const resp = await elbv2.send(new CreateListenerCommand({
  LoadBalancerArn: "arn:...:loadbalancer/app/web-alb/abc",
  Protocol: "HTTP",
  Port: 80,
  DefaultActions: [{ Type: "forward", TargetGroupArn: "arn:...:targetgroup/web-tg/111" }],
}));
const listenerArn = resp.Listeners?.[0].ListenerArn;

Every listener has exactly one default action. Rules are optional refinements you add on top; without any, all traffic follows the default.

Working Example

Now add a rule that sends requests under /api/* to a separate api-tg target group. A rule needs a Priority, a list of Conditions, and a list of Actions.

# --- Python (boto3) ---
import boto3
 
elbv2 = boto3.client("elbv2", region_name="us-east-1")
elbv2.create_rule(
    ListenerArn=listener_arn,
    Priority=10,
    Conditions=[
        {"Field": "path-pattern", "PathPatternConfig": {"Values": ["/api/*"]}},
    ],
    Actions=[{"Type": "forward", "TargetGroupArn": "arn:...:targetgroup/api-tg/222"}],
)

// --- TypeScript (AWS SDK v3) ---
import { ElasticLoadBalancingV2Client, CreateRuleCommand } from "@aws-sdk/client-elastic-load-balancing-v2";
 
const elbv2 = new ElasticLoadBalancingV2Client({ region: "us-east-1" });
await elbv2.send(new CreateRuleCommand({
  ListenerArn: listenerArn,
  Priority: 10,
  Conditions: [
    { Field: "path-pattern", PathPatternConfig: { Values: ["/api/*"] } },
  ],
  Actions: [{ Type: "forward", TargetGroupArn: "arn:...:targetgroup/api-tg/222" }],
}));

Now a request to /api/orders matches this rule and goes to api-tg; a request to / matches no rule and falls through to the listener's default web-tg. Combine conditions to be more specific - a host-header condition alongside the path restricts the rule to one hostname.

# --- Python (boto3) ---
elbv2.create_rule(
    ListenerArn=listener_arn,
    Priority=20,
    Conditions=[
        {"Field": "host-header", "HostHeaderConfig": {"Values": ["api.example.com"]}},
        {"Field": "path-pattern", "PathPatternConfig": {"Values": ["/v2/*"]}},
    ],
    Actions=[{"Type": "forward", "TargetGroupArn": "arn:...:targetgroup/api-v2-tg/333"}],
)

// --- TypeScript (AWS SDK v3) ---
await elbv2.send(new CreateRuleCommand({
  ListenerArn: listenerArn,
  Priority: 20,
  Conditions: [
    { Field: "host-header", HostHeaderConfig: { Values: ["api.example.com"] } },
    { Field: "path-pattern", PathPatternConfig: { Values: ["/v2/*"] } },
  ],
  Actions: [{ Type: "forward", TargetGroupArn: "arn:...:targetgroup/api-v2-tg/333" }],
}));

Multiple conditions on one rule are combined with AND: both the host and the path must match. Values within a single condition are OR, so Values: ["/v2/*", "/v3/*"] matches either prefix.

Deep Dive

How Rules Are Evaluated

Rules are evaluated in ascending Priority order - the lowest number first - and the first rule whose conditions all match wins. Evaluation stops there; later rules never run. The default action is the implicit last resort at the very end.

This ordering is the whole game. Put your most specific rules at low priority numbers and broader ones higher. If a catch-all /api/* rule sits at priority 10 and a specific /api/health rule sits at priority 20, the health rule is unreachable because /api/* already matched. Reverse them.

Priorities must be unique per listener. Leave gaps - 10, 20, 30 - so you can insert a new rule between two existing ones without renumbering everything. To reorder later, use SetRulePriorities.

Action Types Beyond Forward

A forward action is the common case, but two others solve routing problems without a target group.

A redirect action sends a 301 or 302 without touching a backend. The canonical use is forcing HTTPS: an HTTP listener on port 80 whose default action redirects to https://.

# --- Python (boto3) ---
elbv2.create_listener(
    LoadBalancerArn="arn:...:loadbalancer/app/web-alb/abc",
    Protocol="HTTP",
    Port=80,
    DefaultActions=[{
        "Type": "redirect",
        "RedirectConfig": {
            "Protocol": "HTTPS", "Port": "443", "StatusCode": "HTTP_301",
        },
    }],
)

// --- TypeScript (AWS SDK v3) ---
await elbv2.send(new CreateListenerCommand({
  LoadBalancerArn: "arn:...:loadbalancer/app/web-alb/abc",
  Protocol: "HTTP",
  Port: 80,
  DefaultActions: [{
    Type: "redirect",
    RedirectConfig: {
      Protocol: "HTTPS", Port: "443", StatusCode: "HTTP_301",
    },
  }],
}));

A fixed-response action returns a canned body straight from the ALB - handy for a maintenance page or blocking a path.

# --- Python (boto3) ---
elbv2.create_rule(
    ListenerArn=listener_arn,
    Priority=5,
    Conditions=[{"Field": "path-pattern", "PathPatternConfig": {"Values": ["/blocked/*"]}}],
    Actions=[{
        "Type": "fixed-response",
        "FixedResponseConfig": {"StatusCode": "403", "ContentType": "text/plain",
                                 "MessageBody": "Forbidden"},
    }],
)

// --- TypeScript (AWS SDK v3) ---
await elbv2.send(new CreateRuleCommand({
  ListenerArn: listenerArn,
  Priority: 5,
  Conditions: [{ Field: "path-pattern", PathPatternConfig: { Values: ["/blocked/*"] } }],
  Actions: [{
    Type: "fixed-response",
    FixedResponseConfig: { StatusCode: "403", ContentType: "text/plain",
                            MessageBody: "Forbidden" },
  }],
}));

Other condition fields include http-header, http-request-method, query-string, and source-ip, letting you route on almost any property of the request.

Gotchas

Rule order is priority, not creation order. A specific rule placed at a higher number than a broad one is shadowed and never fires. Order by specificity.
Duplicate priorities are rejected. Each rule needs a unique priority per listener; use SetRulePriorities to reshuffle.
path-pattern is not a full regex. It supports * and ? wildcards only, and it matches the path, not the query string - use a query-string condition for that.
Forgetting the default action. Every listener must have one; requests matching no rule fall to it, so make it a sensible fallback, not an accident.
Case and trailing slashes. Path matching is case-sensitive and literal, so /API/* will not match /api/orders. Normalize your patterns.
No gaps in priorities. Numbering rules 1, 2, 3 leaves nowhere to insert; space them 10, 20, 30 from the start.

Alternatives

Separate load balancers per service when isolation (different security groups, WAF rules, or accounts) matters more than sharing one ALB.
Amazon API Gateway when you need request/response transformation, per-route auth, usage plans, and throttling rather than raw L7 routing.
A service mesh (App Mesh) or ingress controller inside ECS/EKS when routing decisions belong next to the workload and change with deployments.
CloudFront in front of the ALB for edge caching and path-based origin routing at the CDN layer.

Use ALB listener rules when several HTTP services should share one entry point and you want routing managed as load-balancer config; reach for the alternatives when you need transformation, isolation, or edge behavior.

FAQs

What is the difference between a listener and a rule?

A listener accepts connections on a protocol and port and has one default action. Rules are prioritized conditions layered on the listener that route matching requests to different actions before the default applies.

In what order are rules evaluated?

By Priority, lowest number first. The first rule whose conditions all match wins and evaluation stops; if none match, the listener's default action runs.

How do I combine multiple conditions?

Put several conditions on one rule - they are ANDed, so all must match. Multiple values inside a single condition are ORed.

What condition fields can I route on?

path-pattern, host-header, http-header, http-request-method, query-string, and source-ip.

How do I redirect HTTP to HTTPS?

Give the port 80 listener a default redirect action with RedirectConfig set to Protocol: "HTTPS", Port: "443", and StatusCode: "HTTP_301".

Can the ALB return a response without a backend?

Yes. A fixed-response action returns a canned status code, content type, and body directly from the load balancer - useful for maintenance pages or blocking paths.

Why is one of my rules never matching?

Usually a broader rule at a lower priority number matches first and shadows it. Reorder so specific rules have lower priority numbers than general ones.

Does path-pattern support regular expressions?

No. It supports only * and ? wildcards and matches the URL path (not the query string). Use a query-string condition to match query parameters.

How do I reorder existing rules?

Call SetRulePriorities with the rule ARNs and their new priority numbers. Priorities must stay unique per listener.

Do NLBs support routing rules?

No. Content-based rules are a Layer 7 ALB feature. An NLB listener forwards by port to a target group with no path or host conditions.

Load Balancing Basics - create the ALB and target group these rules route to.
Target Groups & Health Check Tuning - the backend pools a forward action points at.
TLS Termination & ACM Integration - the HTTPS listener a redirect rule sends traffic to.
ALB vs NLB: Choosing a Load Balancer Type - why routing rules exist only on the ALB.

Stack versions: This page was written for boto3 1.43.x (Python 3.10+) and the AWS SDK for JavaScript v3 (Node.js 18+).

Recipe

Start with the listener. Its DefaultActions is the fallback that runs when no rule matches - here, forward everything to a web-tg target group on port 80.

# --- Python (boto3) ---
import boto3
 
elbv2 = boto3.client("elbv2", region_name="us-east-1")
resp = elbv2.create_listener(
    LoadBalancerArn="arn:...:loadbalancer/app/web-alb/abc",
    Protocol="HTTP",
    Port=80,
    DefaultActions=[{"Type": "forward", "TargetGroupArn": "arn:...:targetgroup/web-tg/111"}],
)
listener_arn = resp["Listeners"][0]["ListenerArn"]

// --- TypeScript (AWS SDK v3) ---
import { ElasticLoadBalancingV2Client, CreateListenerCommand } from "@aws-sdk/client-elastic-load-balancing-v2";
 
const elbv2 = new ElasticLoadBalancingV2Client({ region: "us-east-1" });
const resp = await elbv2.send(new CreateListenerCommand({
  LoadBalancerArn: "arn:...:loadbalancer/app/web-alb/abc",
  Protocol: "HTTP",
  Port: 80,
  DefaultActions: [{ Type: "forward", TargetGroupArn: "arn:...:targetgroup/web-tg/111" }],
}));
const listenerArn = resp.Listeners?.[0].ListenerArn;

Every listener has exactly one default action. Rules are optional refinements you add on top; without any, all traffic follows the default.

Working Example

Now add a rule that sends requests under /api/* to a separate api-tg target group. A rule needs a Priority, a list of Conditions, and a list of Actions.

# --- Python (boto3) ---
import boto3
 
elbv2 = boto3.client("elbv2", region_name="us-east-1")
elbv2.create_rule(
    ListenerArn=listener_arn,
    Priority=10,
    Conditions=[
        {"Field": "path-pattern", "PathPatternConfig": {"Values": ["/api/*"]}},
    ],
    Actions=[{"Type": "forward", "TargetGroupArn": "arn:...:targetgroup/api-tg/222"}],
)

// --- TypeScript (AWS SDK v3) ---
import { ElasticLoadBalancingV2Client, CreateRuleCommand } from "@aws-sdk/client-elastic-load-balancing-v2";
 
const elbv2 = new ElasticLoadBalancingV2Client({ region: "us-east-1" });
await elbv2.send(new CreateRuleCommand({
  ListenerArn: listenerArn,
  Priority: 10,
  Conditions: [
    { Field: "path-pattern", PathPatternConfig: { Values: ["/api/*"] } },
  ],
  Actions: [{ Type: "forward", TargetGroupArn: "arn:...:targetgroup/api-tg/222" }],
}));

# --- Python (boto3) ---
elbv2.create_rule(
    ListenerArn=listener_arn,
    Priority=20,
    Conditions=[
        {"Field": "host-header", "HostHeaderConfig": {"Values": ["api.example.com"]}},
        {"Field": "path-pattern", "PathPatternConfig": {"Values": ["/v2/*"]}},
    ],
    Actions=[{"Type": "forward", "TargetGroupArn": "arn:...:targetgroup/api-v2-tg/333"}],
)

// --- TypeScript (AWS SDK v3) ---
await elbv2.send(new CreateRuleCommand({
  ListenerArn: listenerArn,
  Priority: 20,
  Conditions: [
    { Field: "host-header", HostHeaderConfig: { Values: ["api.example.com"] } },
    { Field: "path-pattern", PathPatternConfig: { Values: ["/v2/*"] } },
  ],
  Actions: [{ Type: "forward", TargetGroupArn: "arn:...:targetgroup/api-v2-tg/333" }],
}));

Multiple conditions on one rule are combined with AND: both the host and the path must match. Values within a single condition are OR, so Values: ["/v2/*", "/v3/*"] matches either prefix.

Deep Dive

How Rules Are Evaluated

Priorities must be unique per listener. Leave gaps - 10, 20, 30 - so you can insert a new rule between two existing ones without renumbering everything. To reorder later, use SetRulePriorities.

Action Types Beyond Forward

A forward action is the common case, but two others solve routing problems without a target group.

A redirect action sends a 301 or 302 without touching a backend. The canonical use is forcing HTTPS: an HTTP listener on port 80 whose default action redirects to https://.

# --- Python (boto3) ---
elbv2.create_listener(
    LoadBalancerArn="arn:...:loadbalancer/app/web-alb/abc",
    Protocol="HTTP",
    Port=80,
    DefaultActions=[{
        "Type": "redirect",
        "RedirectConfig": {
            "Protocol": "HTTPS", "Port": "443", "StatusCode": "HTTP_301",
        },
    }],
)

// --- TypeScript (AWS SDK v3) ---
await elbv2.send(new CreateListenerCommand({
  LoadBalancerArn: "arn:...:loadbalancer/app/web-alb/abc",
  Protocol: "HTTP",
  Port: 80,
  DefaultActions: [{
    Type: "redirect",
    RedirectConfig: {
      Protocol: "HTTPS", Port: "443", StatusCode: "HTTP_301",
    },
  }],
}));

A fixed-response action returns a canned body straight from the ALB - handy for a maintenance page or blocking a path.

# --- Python (boto3) ---
elbv2.create_rule(
    ListenerArn=listener_arn,
    Priority=5,
    Conditions=[{"Field": "path-pattern", "PathPatternConfig": {"Values": ["/blocked/*"]}}],
    Actions=[{
        "Type": "fixed-response",
        "FixedResponseConfig": {"StatusCode": "403", "ContentType": "text/plain",
                                 "MessageBody": "Forbidden"},
    }],
)

// --- TypeScript (AWS SDK v3) ---
await elbv2.send(new CreateRuleCommand({
  ListenerArn: listenerArn,
  Priority: 5,
  Conditions: [{ Field: "path-pattern", PathPatternConfig: { Values: ["/blocked/*"] } }],
  Actions: [{
    Type: "fixed-response",
    FixedResponseConfig: { StatusCode: "403", ContentType: "text/plain",
                            MessageBody: "Forbidden" },
  }],
}));

Other condition fields include http-header, http-request-method, query-string, and source-ip, letting you route on almost any property of the request.

Gotchas

Rule order is priority, not creation order. A specific rule placed at a higher number than a broad one is shadowed and never fires. Order by specificity.
Duplicate priorities are rejected. Each rule needs a unique priority per listener; use SetRulePriorities to reshuffle.
path-pattern is not a full regex. It supports * and ? wildcards only, and it matches the path, not the query string - use a query-string condition for that.
Forgetting the default action. Every listener must have one; requests matching no rule fall to it, so make it a sensible fallback, not an accident.
Case and trailing slashes. Path matching is case-sensitive and literal, so /API/* will not match /api/orders. Normalize your patterns.
No gaps in priorities. Numbering rules 1, 2, 3 leaves nowhere to insert; space them 10, 20, 30 from the start.

Alternatives

Separate load balancers per service when isolation (different security groups, WAF rules, or accounts) matters more than sharing one ALB.
Amazon API Gateway when you need request/response transformation, per-route auth, usage plans, and throttling rather than raw L7 routing.
A service mesh (App Mesh) or ingress controller inside ECS/EKS when routing decisions belong next to the workload and change with deployments.
CloudFront in front of the ALB for edge caching and path-based origin routing at the CDN layer.

FAQs

What is the difference between a listener and a rule?

In what order are rules evaluated?

By Priority, lowest number first. The first rule whose conditions all match wins and evaluation stops; if none match, the listener's default action runs.

How do I combine multiple conditions?

Put several conditions on one rule - they are ANDed, so all must match. Multiple values inside a single condition are ORed.

What condition fields can I route on?

path-pattern, host-header, http-header, http-request-method, query-string, and source-ip.

How do I redirect HTTP to HTTPS?

Give the port 80 listener a default redirect action with RedirectConfig set to Protocol: "HTTPS", Port: "443", and StatusCode: "HTTP_301".

Can the ALB return a response without a backend?

Yes. A fixed-response action returns a canned status code, content type, and body directly from the load balancer - useful for maintenance pages or blocking paths.

Why is one of my rules never matching?

Usually a broader rule at a lower priority number matches first and shadows it. Reorder so specific rules have lower priority numbers than general ones.

Does path-pattern support regular expressions?

No. It supports only * and ? wildcards and matches the URL path (not the query string). Use a query-string condition to match query parameters.

How do I reorder existing rules?

Call SetRulePriorities with the rule ARNs and their new priority numbers. Priorities must stay unique per listener.

Do NLBs support routing rules?

No. Content-based rules are a Layer 7 ALB feature. An NLB listener forwards by port to a target group with no path or host conditions.

Load Balancing Basics - create the ALB and target group these rules route to.
Target Groups & Health Check Tuning - the backend pools a forward action points at.
TLS Termination & ACM Integration - the HTTPS listener a redirect rule sends traffic to.
ALB vs NLB: Choosing a Load Balancer Type - why routing rules exist only on the ALB.

Stack versions: This page was written for boto3 1.43.x (Python 3.10+) and the AWS SDK for JavaScript v3 (Node.js 18+).

Listeners & Routing Rules

Search Documentation

Listeners & Routing Rules