Workload settings

A workload is the object that receives traffic for a set of domains. It holds the domains, the infrastructure it runs on, the HTTP versions and ports, the TLS settings, and mTLS. A sub-object of the workload, the deployment, names the application, the firewall, and the custom page set that serve that traffic. This page lists every field of both objects by its API name, with the Console control beside it. For the numeric bounds in one place, refer to Workloads limits. For the path a request follows through these objects, refer to How Workloads works.

Interfaces

Four interfaces write the same two objects. The tables on this page name the Console control, the API field, and the CLI flag of each field.

azion create workload sets name and active from flags; every other workload field goes in the JSON file of --file. azion update workload --file reads the workload ID from an "id" key inside that file. The CLI has no command that updates or deletes a deployment. Change a deployment’s application, firewall, or custom page set in the Console or with the API PATCH.

On API v3, the protocol and TLS settings of this page lived in an application’s Main Settings. On API v4 they belong to the workload. For the full mapping between the two models, refer to API v4 Migration.

General

The general fields identify the workload and record who changed it. The API requires name and nothing else. Every other field in this table is read-only, except active.

The name labels the workload in your account and is not a domain address, so you can change it at any time. A name of 101 characters or more is refused with Ensure this field has no more than 100 characters.

Infrastructure

The infrastructure field chooses the network that serves the workload and the suffix of its workload domain. In the Console, the Infrastructure section reads: “Select the infrastructure type for your Workload. Once this option is saved, it cannot be modified.”

The two values differ in where the workload runs and in the domains it accepts:

A staging workload is reached only through its workload domain, and changes made to it do not affect the production workload. The value is fixed at creation: an update that changes it is refused with The infrastructure cannot be changed after Workload creation. For example, to move a configuration tested on staging to production, you create a second workload with infrastructure set to 1 instead of editing the first.

Domains

The domain fields decide which hostnames the workload answers. Every workload gets a read-only workload domain, and domains adds your own hostnames and the optional free azion.app hostname that the Console calls Azion Custom Domain. The Console section Domains writes all three fields.

The Domain field takes a domain you type or one you select from Edge DNS. The Azion Custom Domain field takes a name such as my-custom-name and appends .azion.app, and the full hostname is stored in domains beside your own. The azion.app hostname is available at no additional cost.

workload_domain_allow_access set to true lets clients reach the workload on its workload domain, whatever else domains holds. Set it to false when the workload must answer only on your own hostnames. To point your own domain at the workload domain, refer to Point a domain to a workload.

The API applies these rules to domains:

The API stores each hostname with the case you send: Docs-Rework-Upper.azion.app reads back unchanged.

Protocols and ports

The protocols.http object sets the HTTP versions the workload accepts and the ports it listens on. In the Console, the Protocol Settings section writes it, through two switches and three port lists.

HTTP/3 runs over QUIC. The Console help text for HTTP/3 support reads “Enable HTTP/3 over QUIC. Requires HTTPS support to be enabled.”, and the API adds a second dependency on versions: a list with http3 must also hold http1 and http2. Otherwise the API refuses it with Missing required choices for multiple choices field: ['http1', 'http2'].

An HTTP port outside the four values is refused with Invalid choices for multiple choices field: [80, 8008, 8080, 8880]. For example, a workload that serves HTTP on 8080 alongside 80 sends "http_ports": [80, 8080]. For the delivery and origin port combinations an application can use, refer to Configure HTTP and HTTPS ports.

TLS

Transport Layer Security (TLS) encrypts the connection between a client and the workload. The tls object names the certificate the workload presents, the lowest TLS version it accepts, and the cipher suite it offers. In the Console, these controls sit in the Protocol Settings section, and Digital Certificate appears when the HTTPS support switch is on.

HTTPS needs an X.509 certificate. You can upload your own certificate to Certificate Manager or request a Let’s Encrypt certificate that Azion manages, both at no additional cost. With tls.certificate set to null, the workload presents the Azion SAN certificate, which covers the Azion Custom Domain and the workload domain. A certificate of another type is refused: a Trusted CA certificate in tls.certificate returns Invalid certificate type, MUST be an Edge Certificate.

tls.minimum_version sets a floor, not the exact version a session uses. A workload with tls_1_2 can still serve a session over TLS 1.3, depending on the cipher the client and the workload negotiate from the suite. Azion blocks TLS renegotiation and TLS resumption by default. To change that, contact the Sales team.

The cipher suite decides which cryptographic algorithms a TLS connection may use. The client and the workload negotiate one cipher from the suite for each session. The API refuses a value outside 1 to 8. For 9, the message is "9" is not a valid choice. To change the suite step by step, refer to Set the TLS cipher suite.

Cipher suites

Each value of tls.ciphers selects one named suite. The tables below list the ciphers each suite holds, with the TLS version each cipher belongs to.

Suite 1, TLSv1.2_2018

ciphers: 1 selects TLSv1.2_2018, which holds three TLS 1.3 ciphers and 13 TLS 1.2 ciphers:

Suite 2, TLSv1.2_2019

ciphers: 2 selects TLSv1.2_2019, which holds three TLS 1.3 ciphers and 10 TLS 1.2 ciphers:

Suite 3, TLSv1.3_2022

ciphers: 3 selects TLSv1.3_2022, which holds six TLS 1.2 ciphers:

Suite 4, TLSv1.2_2021

ciphers: 4 selects TLSv1.2_2021, which holds three TLS 1.3 ciphers and six TLS 1.2 ciphers:

Suite 5, Legacy_v2025Q1

ciphers: 5 selects Legacy_v2025Q1, which holds three TLS 1.3 ciphers and 15 TLS 1.2 ciphers:

Suite 6, Compatible_v2025Q1

ciphers: 6 selects Compatible_v2025Q1, which holds three TLS 1.3 ciphers and 12 TLS 1.2 ciphers:

Suite 7, Modern_v2025Q1

ciphers: 7 selects Modern_v2025Q1, which holds three TLS 1.3 ciphers and six TLS 1.2 ciphers:

Suite 8, Legacy_v2017Q1

ciphers: 8 selects Legacy_v2017Q1, which holds three TLS 1.3 ciphers and 26 TLS 1.2 ciphers:

mTLS

Mutual TLS (mTLS) makes the client present a certificate too, and the workload checks it against a certificate authority you trust. The mtls object turns the check on and names the Trusted CA certificate and the certificate revocation lists (CRLs) it uses. Set it through the API or the JSON file of azion update workload --file.

A server certificate in mtls.config.certificate is refused with Invalid certificate type, MUST be a Trusted CA. For example, a workload that checks client certificates against your CA and one CRL, in enforce mode, sends "mtls": {"enabled": true, "config": {"certificate": <trusted-ca-id>, "crl": [<crl-id>], "verification": "enforce"}}. For how enforce and permissive treat a client certificate, refer to mTLS.

Deployment

A deployment binds the application, the firewall, and the custom page set that serve a workload’s traffic. It is a sub-resource of the workload, at /v4/workspace/workloads/{workload_id}/deployments, and a workload holds one deployment. A second one is refused with The maximum number of deployments allowed per workload is 1. In the Console, the Deployment Settings section of the workload writes it.

strategy.attributes holds exactly these three keys. A deployment created without a custom page set reads "custom_page": null. A deployment without a firewall shows Select a Firewall in the Console Firewall field and 0 in azion list workload-deployment --details. A custom page set takes effect only when the deployment names it in custom_page. A workload that still uses a firewall keeps that firewall from being deleted, and deleting the deployment does not release it: delete the workload first.

Request body

The JSON body below creates a staging workload with TLS 1.2 as the floor, cipher suite 4, and two HTTP and two HTTPS ports. The same body works for POST /v4/workspace/workloads and for the file of azion create workload --file:

Send it with the CLI, with the body saved as wl-staging.json:

The command prints the ID of the new workload:

azion describe workload --workload-id <workload-id> --format json then returns the workload as the API stores it, with its staging workload domain:

Through the API, POST /v4/workspace/workloads answers with HTTP 202 and state set to pending. A production workload created with name, active, infrastructure, and workload_domain_allow_access alone returns every default:

The deployment body below binds an application and a firewall through POST /v4/workspace/workloads/{workload_id}/deployments:

The API answers with HTTP 202, state set to pending, and the deployment with custom_page set to null:

The CLI creates the same binding from flags, here with an application and a custom page set:

The command prints the ID of the new deployment:

azion list workload-deployment --workload-id <workload-id> --details shows the deployment, its application, and its firewall, with 0 for no firewall:

Errors

The API refuses each request below with the message in the first column. For a workload or deployment refusal, the CLI prints the message inside Error: Failed to create the Workload: [...], Error: Failed to update the Workload: [...], or Error: Failed to create the Workload Deployment: [...], followed by Check your settings and try again. If the error persists, contact Azion support. The 24003 row is the API’s answer to a firewall DELETE.

Related resources