github.com/swisspost/terratest@v0.0.0-20230214120104-7ec6de2e1ae0/test-docker-images/moto/README.md (about)

     1  # Moto
     2  
     3  This docker image runs [moto](https://github.com/spulec/moto) as a service. We will use Moto as a local service that
     4  accepts AWS API calls and returns valid API responses. Moto can be used with any AWS SDK, including the [awscli](
     5  https://aws.amazon.com/cli/)[].
     6  
     7  This Docker image is expected to run alongside a cluster of docker containers to represent a "local AWS".
     8  
     9  ### About Moto
    10  
    11  Moto was originally written as a way to mock out the Python [boto](https://github.com/boto/boto3) library, the official
    12  AWS SDK for Python. It was motivated by the need to write automated tests for boto. But since the AWS API cannot run
    13  "locally", Moto was written to mock the responses of the AWS API.
    14  
    15  Moto works by receiving AWS API requests across a wide variety of AWS services, including most of EC2. It will then store
    16  the requested AWS resource in memory and allow you to query that AWS resource using standard AWS API calls. There is
    17  no actual VM created, or other actual resource created.
    18  
    19  ### Motivation
    20  
    21  As part of writing [Unit Tests with Terratest](/README.md#unit-tests), we need a way to run our services in a Docker
    22  container. But this presents a new challenge: Almost all our cluster-based setups query the AWS APIs to obtain metadata
    23  about the EC2 Instance on which they're running. How can we simulate these API calls in a local environment? Moto seems
    24  to meet this use case perfectly.
    25  
    26  ## Usage
    27  
    28  ### Building and Pushing a New Docker Image to Docker Hub
    29  
    30  This Docker image should publicly accessible via Docker Hub at https://hub.docker.com/r/gruntwork/moto/. To build and
    31  upload it:
    32  
    33  1. `docker build -t gruntwork/moto:v1 .`
    34  1. `docker push gruntwork/moto:v1`
    35  
    36  #### Run a Docker container
    37  
    38  ```
    39  docker run -p 5000:5000 gruntwork/moto moto_server ec2 --host 0.0.0.0
    40  ```
    41  
    42  This runs the `moto` service as a RESTful API, specially for the AWS EC2 API with support for acceping connections from
    43  any IP address (versus just from localhost). For additional information:
    44  - See the [moto stand-alone server usage docs](https://github.com/spulec/moto#stand-alone-server-mode)
    45  - See [which AWS services are supported](https://github.com/spulec/moto#in-a-nutshell)
    46  
    47  #### Make AWS API calls against Moto
    48  
    49  Because Moto exposes an API that is intended to be identical to the official AWS API, you can use any any AWS SDK against
    50  it, including the AWS CLI, AWS SDK for Go, `curl` calls, or any other AWS API library. The only difference is that you
    51  must explicitly set the "endpoint uRL" to point to the Moto server instead of the official AWS API. Changing this setting
    52  will be different for each AWS SDK, but for the AWSCLI, you can simplify specify the `--endpoint-url` argument as follows:
    53  
    54  ```
    55  aws --region "us-west-2" --endpoint-url="http://localhost:5000" ec2 run-instances --image-id ami-abc12345 --tag-specifications 'ResourceType=instance,Tags=[{Key=ServerGroupName,Value=josh}]'
    56  ```
    57  
    58  Note that Moto supports all AWS regions, and will automatically create a VPC with default subnets for you!
    59  
    60  ## Other Solutions Considered
    61  
    62  ### LocalStack
    63  
    64  [LocalStack](https://localstack.cloud/) is a (coming soon) commercial service intending to offer "local AWS as a service".
    65  It is based on the open source [localstack](https://github.com/localstack/localstack) project.
    66  
    67  Local stack seems to offer a [small set of advantages](https://github.com/localstack/localstack#why-localstack) over
    68  Moto, including throwing periodic errors to simulate a real-world cloud environment. But Localstack doesn't implement
    69  100% of the APIs implemented by Moto (including EC2, the most important one for us!), its docker image is ~500 MB, it
    70  doesn't appear to be an active commercial entity, and Moto supports a RESTful API already.
    71  
    72  For these reasons, Moto is the better fit for our needs.