feat(targets): Failover targets for 3.12

[cloudjumpercat]

Description

Fixes #2619

Preview Links

• New section in Targets and Upstreams: https://deploy-preview-2772--kongdeveloper.netlify.app/gateway/entities/target/#managing-failover-targets and https://deploy-preview-2772--kongdeveloper.netlify.app/gateway/entities/upstream/#managing-failover-targets
• New how to doc: https://deploy-preview-2772--kongdeveloper.netlify.app/how-to/route-requests-to-backup-targets/unreleased/ (For reviewers, I can't find a way to do the for i in in a request-check validation block, tried and it didn't work)

For reviewers, decK doesn't support failover yet, so use this to configure your targets in the how to:

# Target 1
curl -sS -X POST http://localhost:8001/upstreams/example-upstream/targets \
  -H "Content-Type: application/json" \
  -d '{
    "target": "host.docker.internal:9001",
    "weight": 100,
    "failover": false
  }'

# Target 2
curl -sS -X POST http://localhost:8001/upstreams/example-upstream/targets \
  -H "Content-Type: application/json" \
  -d '{
    "target": "host.docker.internal:9002",
    "weight": 100,
    "failover": false
  }'

# Target 3
curl -sS -X POST http://localhost:8001/upstreams/example-upstream/targets \
  -H "Content-Type: application/json" \
  -d '{
    "target": "host.docker.internal:9003",
    "weight": 50,
    "failover": true
  }'

Checklist

• Tested how-to docs. If not, note why here.
• All pages contain metadata.
• Any new docs link to existing docs.
• All autogenerated instructions render correctly (API, decK, Konnect, Kong Manager).
• Style guide (capitalized gateway entities, placeholder URLs) implemented correctly.
• Every page has a description entry in frontmatter.
• Add new pages to the product documentation index (if applicable).

[netlify]

✅ Deploy Preview for kongdeveloper ready!

Name	Link
🔨 Latest commit	9e696fc
🔍 Latest deploy log	https://app.netlify.com/projects/kongdeveloper/deploys/68bf31a8b93b6b00091c54fb
😎 Deploy Preview	https://deploy-preview-2772--kongdeveloper.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[lena-larionova]

Ran through it, had no trouble.

Do we know if decK is going to support this before release? If not, then we'll need to use curl (and add a separate command to create an Upstream before creating Targets).

If decK is going to support this soon, then we should mark the version of decK in the prereqs.

[cloudjumpercat]

Do we know if decK is going to support this before release? If not, then we'll need to use curl (and add a separate command to create an Upstream before creating Targets).

If decK is going to support this soon, then we should mark the version of decK in the prereqs.

@lena-larionova I've asked eng about this and will adjust the docs depending on what I hear back.

[locao]

This looks pretty good!

I have just a few comments:

• I didn't see any mention that more than one target can be used as failover. If you think it's worth adding this info, you could say their weights will be respected when choosing which one will proxy the request.
• I see the Target Schema is included from somewhere else. Is it from the code? In the rendered doc it is missing the failover field.
• I think it is worth mentioning nothing blocks the user from adding a failover target to consistent-hashing and sticky-sessions upstreams, but they will be ignored, not used in regular balancing or acting as failover.

[cloudjumpercat]

@locao Thanks for the feedback! I've applied changes for your suggestions. For this:

I see the Target Schema is included from somewhere else. Is it from the code? In the rendered doc it is missing the failover field.

We autogenerate the schema closer to release in our release/gateway-3.12 branch.

[lena-larionova]

@locao Thanks for the feedback! I've applied changes for your suggestions. For this:

I see the Target Schema is included from somewhere else. Is it from the code? In the rendered doc it is missing the failover field.

We autogenerate the schema closer to release in our release/gateway-3.12 branch.

We should be able to do this now - I'll get it updated on the release branch.

[lena-larionova]

LGTM, and pre-approved. You can merge it with decK instructions if our confidence on that is high.

[cloudjumpercat]

You can merge it with decK instructions if our confidence on that is high.

@lena-larionova It's likely decK won't support this with GA, so I've converted the failover examples to API requests.

[cloudjumpercat]

Broken links are expected since the pages are /unreleased