Amazon Account α

Note

This component is available since Platform version 44.

Amazon Account is similar to a regular cloud account since it allows your instance to employ EC2 provisioning. However, it specifically focuses on AWS and can be used, for example, to

  • call ECS API,
  • change S3 file permissions,
  • adjust Route53 DNS records,

All that is possible through the use of amazon-api-call command.

When added to an environment, instances of Amazon Cloud Account implicitly set policies on jcloudsProvider, jcloudsIdentity, jcloudsCredential, jcloudsEndpoint and jcloudsRegions parameters, allowing you to use provisionVms steps just like with the regular Cloud Account service.

Service Descriptor

For using an Amazon Cloud Account instance to interact with AWS API, link it to a manifest using reference.Service component type. Refer to the descriptor below:

compute:
  create-vm:       receive-command(string imageId,
                                   string hardwareId,
                                   string locationId,
                                   object privateKey,
                                   string group,
                                   string login,
                                   map<string, string> metadata,
                                   list<string> networks,
                                   string userData
                                   =>
                                   string id,
                                   map<string,map<string,string>> networks,
                                   map<string, object> credentials,
                                   string state)
  destroy-vm:      receive-command(string id)
  describe-vm:     receive-command(string id
                                   =>
                                   string id,
                                   map<string,map<string,string>> networks,
                                   map<string, object> credentials,
                                   string state)
  amazon-api-call:  receive-command(string method,
                                   string endpoint,
                                   map<string, string> headers,
                                   string body
                                   =>
                                   string body)

Commands

Name Definition
create-vm Create a VM in AWS EC2
describe-vm Get a VM properties from AWS EC2 by its id
destroy-vm Destroy a VM in AWS EC2 by its id
amazon-api-call Make AWS API call

Making direct AWS APIs calls

Using the command amazon-api-call, you can do any type of AWS API requests. The mandatory paramteres are: an API-specific endpoint, request headers and body. The service will handle AWS signing v4 for you.

As a real-world example, you can refer to Amazon ECS Service implementation.

This is how one can describe EC2 instances:

- describe-instances:
    action: aws-ca.amazon-api-call
    parameters:
      method: POST
      endpoint: https://ec2.amazonaws.com/?Action=DescribeInstances&Version=2015-04-15
      headers: {}
      body: ''
    output:
      describe-instances-response: body

Or list hosted zones in Route53:

- list-hosted-zones:
    action: aws-ca.amazon-api-call
    parameters:
      method: GET
      endpoint: https://route53.amazonaws.com/2013-04-01/hostedzone
      headers: {}
      body: ''
    output:
      list-hosted-zones-response: body

The example below retrieves RDS cluster descriptions. Note, that RDS API requires Content-Type: text/plain header instead of the default application/www-x-form-urlencoded used by the AWS client:

- describe-clusters:
    action: aws-ca.amazon-api-call
    parameters:
      method: POST
      endpoint: https://rds.us-east-1.amazonaws.com?Action=DescribeDBClusters&Version=2014-10-31&MaxRecords=100
      headers:
        Content-Type: "text/plain"
      body: ''
    output:
      describe-clusters-response: body

The next example creates an ECS cluster. Unlike some other API calls, this one requires that the caller provides request body. Note the added leading and trailing spaces: they are here to work around implicit string-to-JSON conversion. Of course, all expression escaping rules (like doubling $ and {} signs) still apply.:

- create-cluster:
    action: aws-ca.amazon-api-call
    parameters:
      method: POST
      endpoint: http://ecs.us-east-1.amazonaws.com/
      headers:
        X-Amz-Target: AmazonEC2ContainerServiceV20141113.CreateCluster
        Content-Type: application/x-amz-json-1.1
      body: ' {{ "clusterName": "default" }} '
    output:
      create-cluster-response: body