View a markdown version of this page

Configuration options for Beanstalk Cluster environments - Amazon Elastic Beanstalk
aws:elasticbeanstalk:eksaws:elasticbeanstalk:eks:environmentaws:elasticbeanstalk:eks:environment:deploymentaws:elasticbeanstalk:eks:environment:deployment:strategy:rollingaws:elasticbeanstalk:eks:environment:autoscalingaws:elasticbeanstalk:eks:environment:autoscaling:triggeraws:elasticbeanstalk:eks:environment:autoscaling:behaviorThe container probe namespacesaws:elasticbeanstalk:eks:albaws:elasticbeanstalk:eks:observability
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Configuration options for Beanstalk Cluster environments

A Beanstalk Cluster environment is configured through the twelve namespaces on this page. They are the only namespaces that a Beanstalk Cluster environment accepts. The classic namespaces in Configuration options for Beanstalk Standard environments configure Beanstalk Standard environments and do not apply, and passing one of them to a Beanstalk Cluster environment returns an InvalidParameterValueException rather than being ignored.

For the ways to set these options, and for how Elastic Beanstalk resolves them, see Configuration options.

Note

The Default column gives the value that DescribeConfigurationOptions advertises for the option. Where Elastic Beanstalk applies a value even though it advertises no default, the description says so.

aws:elasticbeanstalk:eks

Configure the IAM roles for the Amazon EKS cluster that runs your environment. You supply both roles, and Elastic Beanstalk requires them when you create the environment. The subnets that you select determine which cluster the environment joins, and Elastic Beanstalk rejects the request if these roles don't match the roles registered for that cluster. For the role names that the console creates, their trusted services, and their policies, see Permissions for Beanstalk Cluster.

The environment also requires an observability role, and it can take an optional application role. Both of those settings are in the aws:elasticbeanstalk:eks:environment namespace rather than this one. See aws:elasticbeanstalk:eks:environment.

Namespace: aws:elasticbeanstalk:eks
Name Description Default Valid values

cluster-role

The ARN of the IAM role that Amazon EKS assumes for the cluster.

None. You must supply a value.

An IAM role ARN

node-role

The ARN of the IAM role that the cluster's Amazon EC2 nodes assume.

None. You must supply a value.

An IAM role ARN

aws:elasticbeanstalk:eks:environment

Configure the application container, the compute it reserves, its network placement, and the roles it uses.

Namespace: aws:elasticbeanstalk:eks:environment
Name Description Default Valid values

application-role

The ARN of an optional IAM role that your application assumes to call Amazon services. See Permissions for Beanstalk Cluster.

None

An IAM role ARN

arch

The CPU architecture that your application runs on.

amd64

amd64 | arm64

cpu

The CPU that each replica of your application reserves. Uses Kubernetes quantity notation, so 500m is half of a virtual CPU and 2 is two virtual CPUs.

250m

0.01 to 128, or 10m to 128000m

cpu-limit

The most CPU that each replica of your application can use. Uses the same notation as cpu.

None

0.01 to 128, or 10m to 128000m

env-variables

The environment variables for the container, as a JSON object that maps each variable name to its value. This is one option that holds every variable, not one option per variable. Elastic Beanstalk sets PORT from service-port and overrides any value that you supply for it.

{"PORT" : 8080}

A JSON object

ingress-allowlist-environments

The names of the environments that may send traffic to this environment. See Multi-tenancy for Beanstalk Cluster environments.

None

A comma-separated list of environment names

ingress-allowlist-groups

The ingress groups whose environments may send traffic to this environment. Every environment in a listed group is allowed.

None

A comma-separated list of ingress group names

ingress-groups

The ingress groups that this environment belongs to. Environments in the same group can reach each other.

None

A comma-separated list of ingress group names

instance-category

The Amazon EC2 instance category that the cluster's nodes are selected from.

None

c | d | g | gr | hpc | i | im | is | m | p | r | t | x | z

language

The runtime language of your application, which selects the OpenTelemetry auto-instrumentation that Elastic Beanstalk adds to your container, so that your application emits metrics, logs, and traces to the observability backends that you select without application changes. This option chooses auto-instrumentation only. It doesn't limit the languages your application can use. Omit it if your runtime isn't listed, or if your application emits OpenTelemetry data on its own.

None

python | java | dotnet | nodejs

load-balancer-type

How traffic reaches your application. With None, Elastic Beanstalk doesn't create a load balancer. See Configuring networking for Beanstalk Cluster environments.

ALB

ALB | None

memory

The memory that each replica of your application reserves. Uses Kubernetes quantity notation, such as 512Mi or 1.5Gi. Fractional values are accepted.

512Mi

A Kubernetes memory quantity

memory-limit

The most memory that each replica of your application can use. Uses the same notation as memory.

1Gi

A Kubernetes memory quantity

node-pool

The name of the node pool that runs this environment's replicas. A unique value gives the environment its own nodes, and a shared value groups environments onto shared nodes. See Multi-tenancy for Beanstalk Cluster environments.

None

A DNS-1123 label

observability-role

The ARN of the IAM role that publishes the environment's metrics, logs, and traces. Elastic Beanstalk requires it, and it must match the role registered for the cluster that your subnets select. There is no default, so supply it explicitly. See Permissions for Beanstalk Cluster.

None. You must supply a value.

An IAM role ARN

secrets

The secrets to expose to the container, as a JSON object that maps each name to the ARN of a secret in Secrets Manager or a parameter in Systems Manager Parameter Store. Like env-variables, this is one option that holds every secret. Requires application-role: Elastic Beanstalk reads each secret through the pod's identity, which exists only when you set that option. Without it, the volume mount fails and your replicas never start.

None

A JSON object

service-port

The port that your application listens on. Elastic Beanstalk requires it, injects it into the container as the PORT environment variable, and uses it as the port that other environments and the container probes reach.

8080

1 to 65535

subnets

The subnets for the environment. They determine where the cluster's nodes run and which cluster the environment joins. If you omit them, Elastic Beanstalk uses the public subnets of the default VPC. You can't change them after you create the environment. See Configuring networking for Beanstalk Cluster environments.

None

A comma-separated list of subnet IDs

aws:elasticbeanstalk:eks:environment:deployment

Choose how Elastic Beanstalk replaces the running replicas of your application when you deploy a new application version.

Namespace: aws:elasticbeanstalk:eks:environment:deployment
Name Description Default Valid values

strategy

The deployment strategy. RollingUpdate replaces replicas gradually, and Recreate takes all of them down and starts the new version, which is the strategy that the console calls all at once. See Choosing a deployment policy.

RollingUpdate

RollingUpdate | Recreate

aws:elasticbeanstalk:eks:environment:deployment:strategy:rolling

Bound how far a rolling deployment may run ahead of, or behind, the number of replicas that the environment is running. These options apply when strategy is RollingUpdate.

Namespace: aws:elasticbeanstalk:eks:environment:deployment:strategy:rolling
Name Description Default Valid values

max-surge

How many replicas Elastic Beanstalk may start beyond the environment's current replica count while it deploys.

1

A count, such as 2, or a percentage, such as 25%

max-unavailable

How many of the environment's replicas may be unavailable at one time while it deploys.

0

A count, such as 1, or a percentage, such as 25%

aws:elasticbeanstalk:eks:environment:autoscaling

Set the number of replicas that Elastic Beanstalk runs for your application, and how often it evaluates whether to change that number.

If you configure no trigger, Elastic Beanstalk scales the environment on CPU utilization with a target of 80 percent, between min-replica and max-replica. To scale on something else, set a trigger. See aws:elasticbeanstalk:eks:environment:autoscaling:trigger.

Namespace: aws:elasticbeanstalk:eks:environment:autoscaling
Name Description Default Valid values

min-replica

The fewest replicas of your application that the environment runs.

1

1 to 100

max-replica

The most replicas of your application that the environment runs.

10

1 to 100

polling-interval

How often, in seconds, Elastic Beanstalk evaluates the scaling triggers.

30

1 to 1000

cooldown-period

How long, in seconds, Elastic Beanstalk waits after the last trigger stops reporting activity before it scales the environment back down.

300

An integer of 1 or greater

aws:elasticbeanstalk:eks:environment:autoscaling:trigger

Choose what makes the environment scale. You can scale on the CPU or memory that your replicas use, and you can scale on a schedule or on a metric that your own endpoint reports. These options have no advertised defaults. When you set none of them, Elastic Beanstalk supplies a CPU trigger with cpu-metric-type set to Utilization and cpu-value set to 80.

Namespace: aws:elasticbeanstalk:eks:environment:autoscaling:trigger
Name Description Default Valid values

cpu-metric-type

Whether the CPU trigger compares a percentage of the reserved CPU (Utilization) or an absolute amount (AverageValue).

None. Elastic Beanstalk applies Utilization if you set cpu-value alone, or if you set no trigger at all.

Utilization | AverageValue

cpu-value

The CPU target that the environment scales to hold. With Utilization, a value of 60 means 60 percent of the reserved CPU.

None. Elastic Beanstalk applies 80 if you set no trigger at all.

An integer

memory-metric-type

Whether the memory trigger compares a percentage of the reserved memory (Utilization) or an absolute amount (AverageValue).

None. Elastic Beanstalk applies Utilization if you set memory-value alone.

Utilization | AverageValue

memory-value

The memory target that the environment scales to hold.

None

An integer

scaler-type

The kind of event-driven trigger. cron scales on a schedule, and metrics-api scales on a value that Elastic Beanstalk reads from an HTTP endpoint that you supply.

None

cron | metrics-api

scaler-metadata

The settings for the trigger, as a JSON object. With cron, supply timezone, start, end, and desiredReplicas. With metrics-api, supply url, valueLocation, and targetValue.

None

A JSON object

scaler-auth-mode

How Elastic Beanstalk authenticates to the endpoint that a metrics-api trigger reads.

bearer

bearer | basic | apiKey | tls

scaler-auth-secret

The ARN of the Secrets Manager secret that holds the credentials for the endpoint. You can set it only when scaler-type is metrics-api. Requires application-role: Elastic Beanstalk reads the secret through the pod's identity, which exists only when you set that option. Without it, the mount fails and your replicas never start.

None

An Secrets Manager secret ARN

The following example scales the environment to five replicas during weekday working hours in UTC:

$ cat schedule.json
[
  {
    "Namespace": "aws:elasticbeanstalk:eks:environment:autoscaling:trigger",
    "OptionName": "scaler-type",
    "Value": "cron"
  },
  {
    "Namespace": "aws:elasticbeanstalk:eks:environment:autoscaling:trigger",
    "OptionName": "scaler-metadata",
    "Value": "{\"timezone\":\"UTC\",\"start\":\"0 8 * * 1-5\",\"end\":\"0 18 * * 1-5\",\"desiredReplicas\":\"5\"}"
  }
]
$ aws elasticbeanstalk update-environment \
    --environment-name my-cluster-env \
    --option-settings file://schedule.json

A scaler-metadata value is itself a JSON document, so the settings go in a file rather than on the command line.

aws:elasticbeanstalk:eks:environment:autoscaling:behavior

Limit how quickly the environment adds or removes replicas once a trigger fires. Each direction takes a period, a unit, and an amount: within each period, the environment changes the replica count by at most the amount that you set.

Namespace: aws:elasticbeanstalk:eks:environment:autoscaling:behavior
Name Description Default Valid values

scaleup-period

The period, in seconds, that scaleup-value applies to.

None

An integer of 1 or greater

scaleup-type

Whether scaleup-value is a number of replicas (Pods) or a percentage of the current count (Percent).

None

Pods | Percent

scaleup-value

The most that the environment adds within one scaleup-period.

None

An integer

scaledown-period

The period, in seconds, that scaledown-value applies to.

None

An integer of 1 or greater

scaledown-type

Whether scaledown-value is a number of replicas (Pods) or a percentage of the current count (Percent).

None

Pods | Percent

scaledown-value

The most that the environment removes within one scaledown-period.

None

An integer

The container probe namespaces

Three namespaces configure container probes, and each one takes the same nine options:

  • aws:elasticbeanstalk:eks:environment:readiness-probe decides when a replica is ready to receive traffic. A replica that fails it is taken out of service without being restarted.

  • aws:elasticbeanstalk:eks:environment:liveness-probe decides when a replica is unhealthy. A replica that fails it is restarted.

  • aws:elasticbeanstalk:eks:environment:startup-probe gives a slow-starting replica time to initialize before the other two probes begin.

Every probe is off until you enable it. For how probes relate to environment health, see Monitoring Beanstalk Cluster environments.

Namespaces: aws:elasticbeanstalk:eks:environment:readiness-probe, aws:elasticbeanstalk:eks:environment:liveness-probe, and aws:elasticbeanstalk:eks:environment:startup-probe
Name Description Default Valid values

enabled

Whether the probe runs.

false

true | false

http-path

The path that the probe requests.

/

A URL path

http-port

The port that the probe requests. If you omit it, the probe uses service-port.

None. The probe uses service-port.

1 to 65535

initial-delay-seconds

How long the probe waits after a replica starts before its first request.

0

An integer number of seconds

period-seconds

How often the probe runs.

30

1 to 3600

timeout-seconds

How long the probe waits for a response before the request counts as a failure.

5

An integer number of seconds

success-threshold

How many consecutive successes make the probe pass.

1

An integer

failure-threshold

How many consecutive failures make the probe fail.

3

An integer

aws:elasticbeanstalk:eks:alb

Configure the Application Load Balancer in front of your application, its listeners and TLS, and the health check on its target group. These options apply when load-balancer-type is ALB. For the network settings, for supplying a load balancer that you already own, and for the rules that govern the HTTPS listener, see Configuring networking for Beanstalk Cluster environments.

Namespace: aws:elasticbeanstalk:eks:alb
Name Description Default Valid values

arn

The ARN of an Application Load Balancer that you already own, used instead of one that Elastic Beanstalk creates. Elastic Beanstalk rejects the ARN of a Network Load Balancer.

None. Elastic Beanstalk creates a load balancer.

An Application Load Balancer ARN

scheme

Whether the load balancer is reachable from the internet. If you omit it, Elastic Beanstalk derives it from your subnets: public subnets give an internet-facing load balancer, and private subnets give an internal one.

None. Derived from your subnets.

internet-facing | internal

subnets

The subnets to place the load balancer in. If you omit them, it uses the environment's subnets.

None. The environment's subnets.

A comma-separated list of subnet IDs

security-groups

The security groups to attach to the load balancer.

None

A comma-separated list of security group IDs

manage-backend-security-group-rules

Whether Elastic Beanstalk adds and removes the security group rules between the load balancer and your application.

true

true | false

ip-address-type

Whether the load balancer serves IPv4 only or both IPv4 and IPv6. Elastic Beanstalk advertises no default and applies ipv4.

ipv4, applied by Elastic Beanstalk

ipv4 | dualstack

target-type

Whether the load balancer sends traffic to the replicas' IP addresses or to the nodes that run them. Elastic Beanstalk advertises no default and applies ip.

ip, applied by Elastic Beanstalk

ip | instance

listen-ports

The listeners to open, as a JSON array with one object per listener, such as [{"HTTPS":443},{"HTTP":80}]. Each port must be unique. Elastic Beanstalk makes sure that an HTTPS listener exists, and supplies the certificate for it. An HTTP listener redirects to HTTPS rather than serving application traffic.

None. Elastic Beanstalk configures HTTPS on port 443.

A JSON array of protocol-to-port objects

certificate-arn

The ARN of your own ACM certificate to attach to the HTTPS listeners, for example when you serve the environment from a custom domain. You don't need this option for HTTPS to work: Elastic Beanstalk creates and attaches a certificate for the environment's own domain either way. If you set it, the load balancer carries both certificates.

None

An ACM certificate ARN

ssl-policy

The security policy for the HTTPS listeners.

None

An Elastic Load Balancing security policy name

ssl-redirect

Selects which HTTPS port Elastic Beanstalk redirects HTTP requests to. The value must be a port that a configured HTTPS listener uses. Elastic Beanstalk redirects requests that arrive on an HTTP listener whether or not you set this option, so it only changes the target port.

None. Elastic Beanstalk redirects to your HTTPS listener's port.

1 to 65535

backend-protocol

The protocol that the load balancer uses to reach your application.

None

HTTP | HTTPS

backend-protocol-version

The protocol version that the load balancer uses to reach your application. Applies only when backend-protocol is set.

None

HTTP2 | GRPC

healthcheck-path

The path that the target group health check requests.

/

A URL path

healthcheck-protocol

The protocol that the target group health check uses.

HTTP

HTTP | HTTPS

healthcheck-interval-seconds

How often the target group health check runs.

15

5 to 300

healthcheck-timeout-seconds

How long the health check waits for a response.

5

2 to 120

success-codes

The HTTP status codes that count as a successful health check.

200

A status code, a list, or a range

healthy-threshold-count

How many consecutive successful checks make a target healthy.

2

2 to 10

unhealthy-threshold-count

How many consecutive failed checks make a target unhealthy.

2

2 to 10

wafv2-acl-arn

The ARN of the Amazon WAF web ACL to associate with the load balancer.

None

An Amazon WAF web ACL ARN

tags

The tags to apply to the load balancer.

None

A JSON object of tag keys and values

load-balancer-attributes

Load balancer attributes to apply to the load balancer, passed through to Elastic Load Balancing without interpretation.

None

A comma-separated list of key=value pairs, such as idle_timeout.timeout_seconds=300,routing.http2.enabled=false

listener-attributes

Listener attributes to apply to a specific listener, passed through to Elastic Load Balancing without interpretation. Supply only listener attributes here, not load balancer attributes.

None

A JSON array of objects, each mapping a listener to a comma-separated list of key=value pairs, such as [{"HTTPS-8443":"routing.http.response.server.enabled=false"}]

raw-annotation

Annotations to apply directly to the Kubernetes ingress that Elastic Beanstalk generates for your environment. Use this for load balancer behavior that the other options in this namespace don't cover.

None

A JSON array of objects, each mapping an ingress annotation key to its value. Each comma-separated segment of a value must contain exactly one =
Note

load-balancer-attributes, listener-attributes, and raw-annotation pass their values through to the load balancer without interpreting them, so Elastic Beanstalk doesn't validate what an individual attribute or annotation means. When you create an environment, an invalid value prevents the load balancer from being created, so the failure is visible. When you update an environment, Elastic Beanstalk doesn't wait for the load balancer to reconcile, so the operation can succeed before your change takes effect. Confirm the change on the load balancer itself.

aws:elasticbeanstalk:eks:observability

Choose where your application's metrics, logs, and traces go. Elastic Beanstalk provisions and operates the collection components, and you are responsible for instrumenting your application and for access to any destination that you select. See Monitoring Beanstalk Cluster environments.

Namespace: aws:elasticbeanstalk:eks:observability
Name Description Default Valid values

metrics-backend

Where your application's metrics go. amp sends them to Amazon Managed Service for Prometheus and requires metrics-endpoint.

cloudwatch

cloudwatch | amp | custom | none

metrics-endpoint

The Amazon Managed Service for Prometheus remote-write endpoint. Set it only when metrics-backend is amp.

None

A remote-write endpoint URL

logs-backend

Where your application's logs go.

cloudwatch

cloudwatch | s3 | custom | none

traces-backend

Where your application's traces go. Unlike metrics and logs, traces have no backend until you select one.

None

xray | custom | none

custom-config

The OpenTelemetry collector pipeline configuration to use for the signals that you set to custom. Reference each credential as a ${NAME} placeholder that custom-credentials supplies. See Sending observability data to a third-party backend.

None

A collector pipeline configuration, as JSON

custom-credentials

The ARN of an Secrets Manager secret holding the credentials that the collector needs to reach a custom backend. The secret value must be a JSON object whose keys match the placeholders in custom-config. Requires application-role: the collector reads the secret through the pod's identity, which exists only when you set that option, and that role must also be allowed to read the secret.

None

An Secrets Manager secret ARN