AWS elasticbeanstalk medium security documentation change
Summary
Expanded troubleshooting documentation with new sections covering Systems Manager integration, secrets management, environment creation errors, deployment issues, health monitoring, Docker troubleshooting, and security-related guidance for IAM permissions and secret handling
Security assessment
Added explicit guidance for handling secrets via environment variables including IAM permission requirements and authentication errors. Documents security implications of misconfigured instance profiles and secret access. Provides remediation for 'Failed to get secrets' errors related to access control.
Diff
diff --git a/elasticbeanstalk/latest/dg/troubleshooting.md b/elasticbeanstalk/latest/dg/troubleshooting.md index ca730e38f..c9f50f50c 100644 --- a//elasticbeanstalk/latest/dg/troubleshooting.md +++ b//elasticbeanstalk/latest/dg/troubleshooting.md @@ -4,0 +5,2 @@ +Using the Systems Manager toolGeneral guidanceEnvironment variables for secretsEnvironment creationDeploymentsHealthConfigurationDockerFAQTroubleshooting deploymentsDeployment errors + @@ -18 +20,3 @@ This chapter provides guidance for troubleshooting issues with your Elastic Bean -If the health of your environment changes to red, we recommend that you first use the AWS Systems Manager tool that includes predefined runbooks to troubleshoot Elastic Beanstalk. For more information see the [ Using the Systems Manager tool](./troubleshooting-systems-manager.html) in the next section of this chapter. +###### Note + +If the health of your environment changes to red, we recommend that you first use the AWS Systems Manager tool that includes predefined runbooks to troubleshoot Elastic Beanstalk. For more information see the Using the Systems Manager tool. @@ -22 +26,329 @@ If the health of your environment changes to red, we recommend that you first us - * [Using AWS Systems Manager Elastic Beanstalk runbooks](./troubleshooting-systems-manager.html) + * Using AWS Systems Manager Elastic Beanstalk runbooks + + * General guidance for troubleshooting your Elastic Beanstalk environment + + * Environments that access secrets and parameters with environment variables + + * Environment creation and instance launches + + * Deployments + + * Health + + * Configuration + + * Troubleshooting Docker containers + + * FAQ + + * Common Errors + + * Deployment errors + + + + +## Using AWS Systems Manager Elastic Beanstalk runbooks + +You can use Systems Manager to troubleshoot your Elastic Beanstalk environments. To help you get started quickly, Systems Manager provides predefined Automation runbooks for Elastic Beanstalk. An Automation runbook is a type of Systems Manager document that defines actions to perform on your environment's instances and other AWS resources. + +The document `AWSSupport-TroubleshootElasticBeanstalk` is an Automation runbook designed to help identify a number of common issues that can degrade your Elastic Beanstalk environment. To do so, it checks components of your environment, including the following: EC2 instances, the VPC, AWS CloudFormation stack, load balancers, Auto Scaling groups, and network configuration associated with security group rules, route tables, and ACLs. + +It also provides an option to upload bundled log files from your environment to AWS Support. + +For more information, see [`AWSSupport-TroubleshootElasticBeanstalk`](https://docs.aws.amazon.com/systems-manager-automation-runbooks/latest/userguide/automation-awssupport-troubleshoot-elastic-beanstalk.html) in the _AWS Systems Manager Automation runbook reference_. + +###### Use Systems Manager to run `AWSSupport-TroubleshootElasticBeanstalk` runbook + +###### Note + +Run this procedure in the same AWS Region where your Elastic Beanstalk environment is located. + + 1. Open the [AWS Systems Manager](https://console.aws.amazon.com/systems-manager/home) console. + + 2. From the navigation pane, in the **Change Management** section, choose **Automation**. + + 3. Choose **Execute automation**. + + 4. On the **Owned by Amazon** tab, in the **Automation document** search box, enter `AWSSupport-TroubleshootElasticBeanstalk`. + + 5. Select the **AWSSupport-TroubleshootElasticBeanstalk** card, then choose **Next**. + + 6. Select **Execute**. + + 7. In the **Input parameters** section: + + 1. From the **AutomationAssumeRole** dropdown, select the ARN of the role that allows Systems Manager to perform actions on your behalf. + + 2. For **ApplicationName** , enter the name of the Elastic Beanstalk application. + + 3. For **Environment Name** , enter the Elastic Beanstalk environment. + + 4. (Optional) For **S3UploaderLink** , enter a link if an AWS Support Engineer has provided you an S3 link for log collection. + + 8. Choose **Execute**. + +If any of the steps fail, select the link under the **Step ID** column for the step that failed. This displays an **Execution detail** page for the step. The **VerificationErrorMessage** section will display a summary of the steps that require attention. For example, the `IAMPermissionCheck` could display a Warning message. In this case, you could check that the role selected in the **AutomationAssumeRole** dropdown has the necessary permissions. + + + + +After all of the steps successfully complete, the output gives troubleshooting steps and recommendations to restore your environment to a healthy state. + +## General guidance for troubleshooting your Elastic Beanstalk environment + +Error messages can appear on the Events page in the console, in logs, or on the Health page. You can also take actions to recover from a degraded environment that was caused by a recent change. If the health of your environment changes to Red, try the following: + + * If an operation on your environment returns an error that contains the text `The stack ``stack_id`` associated with environment ``environment-ID`` is in ``stack-status`` state`, see [Recovering your Elastic Beanstalk environment from an invalid state](./environment-management-invalid-stack.html) for troubleshooting help. + + * If an operation on your environment returns an error that contains the text `Environment `environment-name` associated CloudFormation stack `stack_arn` does not exist`, terminate your environment and create another one. + + * Review recent environment [events](./using-features.events.html). Messages from Elastic Beanstalk about deployment, load, and configuration issues often appear here. + + * Review recent environment [change history](./using-features.changehistory.html). Change history lists all of the configuration changes made to your environments and includes other information, such as which IAM user made changes and which configuration parameters were set. + + * [Pull logs](./using-features.logging.html) to view recent log file entries. Web server logs contain information about incoming requests and errors. + + * [Connect to an instance](./using-features.ec2connect.html) and check system resources. + + * [Roll back](./using-features.deploy-existing-version.html) to a previous working version of the application. + + * Undo recent configuration changes or restore a [saved configuration](./environment-configuration-methods-before.html#configuration-options-before-savedconfig). + + * Deploy a new environment. If the environment appears healthy, perform a [CNAME swap](./using-features.CNAMESwap.html) to route traffic to the new environment and continue to debug the previous one. + + + + +## Environments that access secrets and parameters with environment variables + +**Event:** _Instance deployment failed to get one or more secrets_ + +This message indicates that Elastic Beanstalk was not able to fetch one or more of the secrets specified during your application deployment. + + * Check that the resources specified by the ARN values in your environment variable configuration exist. + + * Confirm that your Elastic Beanstalk EC2 instance profile role has the [required IAM permissions](./AWSHowTo.secrets.IAM-permissions.html#AWSHowTo.secrets.IAM-permissions.secrets-manager) to access the resources. + + * If this event was triggered through the `RestartAppServer` operation, once the issue is fixed, retry the `RestartAppServer` call to resolve the issue. + + * If the event was triggered through an `UpdateEnvironment` call, retry the `UpdateEnvironment` operation. + + + + +For examples of these commands, see [_AWS CLI examples for Elastic Beanstalk_](https://docs.aws.amazon.com/cli/latest/userguide/cli_elastic-beanstalk_code_examples.html). For more information about the API actions for these operations, see the _[AWS Elastic Beanstalk API Reference](https://docs.aws.amazon.com/elasticbeanstalk/latest/api/)_. + +**Event:** _Instance deployment detected one or more multiline environment values, which are not supported for this platform_ + +Multiline variables are not supported for Amazon Linux 2 platforms, excluding Docker and ECS managed Docker platforms. For available options to proceed, see [Multiline values](./AWSHowTo.secrets.env-vars.html#AWSHowTo.secrets.multiline). + +**Event:** _CreateEnvironment fails when a secret is specified_ + +When `CreateEnvironment` fails and you have secrets as environment variables, you need to address the underlying issue and then use `UpdateEnvironment` to complete the environment setup. Do not use `RestartAppServer`, as it will not be sufficient to bring the environment up in this situation. For examples of these commands, see [_AWS CLI examples for Elastic Beanstalk_](https://docs.aws.amazon.com/cli/latest/userguide/cli_elastic-beanstalk_code_examples.html). For more information about the API actions for these operations, see the _[AWS Elastic Beanstalk API Reference](https://docs.aws.amazon.com/elasticbeanstalk/latest/api/)_. + +## Environment creation and instance launches + +**Event:** _Failed to Launch Environment_ + +This event occurs when Elastic Beanstalk attempts to launch an environment and encounters failures along the way. Previous events on the **Events** page will alert you to the root cause of this issue. + +**Event:** _Create environment operation is complete, but with command timeouts. Try increasing the timeout period._ + +Your application may take a long time to deploy if you use configuration files that run commands on the instance, download large files, or install packages. Increase the [command timeout](./using-features.rolling-version-deploy.html#environments-cfg-rollingdeployments-console) to give your application more time to start running during deployments. + +**Event:** _The following resource(s) failed to create: [AWSEBInstanceLaunchWaitCondition]_ + +This message indicates that your environment's Amazon EC2 instances did not communicate to Elastic Beanstalk that they were launched successfully. This can occur if the instances do not have Internet connectivity. If you configured your environment to launch instances in a private VPC subnet, [ensure that the subnet has a NAT](./vpc.html) to allow the instances to connect to Elastic Beanstalk. + +**Event:** _A Service Role is required in this region. Please add a Service Role option to the environment._ + +Elastic Beanstalk uses a service role to monitor the resources in your environment and support [managed platform updates](./environment-platform-update-managed.html). See [Managing Elastic Beanstalk service roles](./iam-servicerole.html) for more information. + +## Deployments + +**Issue:** _Application becomes unavailable during deployments_ + +Because Elastic Beanstalk uses a drop-in upgrade process, there might be a few seconds of downtime. Use [rolling deployments](./using-features.rolling-version-deploy.html) to minimize the effect of deployments on your production environments. + +**Event:** _Failed to create the AWS Elastic Beanstalk application version_ + +Your application source bundle may be too large, or you may have reached the [application version quota](./applications-versions.html). + +**Event:** _Update environment operation is complete, but with command timeouts. Try increasing the timeout period._ + +Your application may take a long time to deploy if you use configuration files that run commands on the instance, download large files, or install packages. Increase the [command timeout](./using-features.rolling-version-deploy.html#environments-cfg-rollingdeployments-console) to give your application more time to start running during deployments. + +## Health + +**Event:** _CPU Utilization Exceeds 95.00%_ + +Try [running more instances](./using-features.managing.as.html), or [choose a different instance type](./using-features.managing.ec2.html). + +**Event:** _Elastic Load Balancer awseb-`myapp` Has Zero Healthy Instances_ + +If your application appears to be working, make sure that your application’s health check URL is configured correctly. If not, check the Health screen and environment logs for more information. + +**Event:** _Elastic Load Balancer awseb-`myapp` Cannot Be Found_ + +Your environment's load balancer may have been removed out-of-band. Only make changes to your environment's resources with the configuration options and [extensibility](./ebextensions.html) provided by Elastic Beanstalk. Rebuild your environment or launch a new one. + +**Event:** _EC2 Instance Launch Failure. Waiting for a New EC2 Instance to Launch..._ + +Availability for your environment's instance type may be low, or you may have reached the instance quota for your account. Check the [service health dashboard](http://status.aws.amazon.com/) to ensure that the Elastic Compute Cloud (Amazon EC2) service is green, or [request a quota increase](https://console.aws.amazon.com/support/home#/case/create?issueType=service-limit-increase&limitType=service-code-ec2-instances). + +## Configuration + +**Event:** _The stack``stack_id`` associated with environment ``environment-ID`` is in ``stack-status`` state_ + +The underlying AWS CloudFormation stack of your environment may be in a _*_FAILED_ status. This status must be remedied in order to continue Elastic Beanstalk operations on your environment. For more information, see [Recovering your Elastic Beanstalk environment from an invalid state](./environment-management-invalid-stack.html). + +**Event:** _You cannot configure an Elastic Beanstalk environment with values for both the Elastic Load Balancing Target option and Application Healthcheck URL option_ + +The `Target` option in the `aws:elb:healthcheck` namespace is deprecated. Remove the `Target` option namespace) from your environment and try updating again. + +**Event:** _ELB cannot be attached to multiple subnets in the same AZ_ +