# salt.states.boto_apigateway

## Manage Apigateway Rest APIs

Added in version 2016.11.0.

depends:

  - boto >= 2.8.0

  - boto3 >= 1.2.1

  - botocore >= 1.4.49

Create and destroy rest apis depending on a swagger version 2 definition file. Be aware that this interacts with Amazon's services, and so may incur charges.

This module uses `boto3`, which can be installed via package, or pip.

This module accepts explicit vpc credentials but can also utilize IAM roles assigned to the instance through Instance Profiles. Dynamic credentials are then automatically obtained from AWS API and no further configuration is necessary. More information available here.

If IAM roles are not used you need to specify them either in a pillar file or in the minion's config file:

    vpc.keyid: GKTADJGHEIQSXMKKRBJ08H
    vpc.key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs

It's also possible to specify `key`, `keyid` and `region` via a profile, either passed in as a dict, or as a string to pull from pillars or minion config:

    myprofile:
      keyid: GKTADJGHEIQSXMKKRBJ08H
      key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs
      region: us-east-1

    Ensure Apigateway API exists:
      boto_apigateway.present:
        - name: myfunction
        - region: us-east-1
        - keyid: GKTADJGHEIQSXMKKRBJ08H
        - key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs

salt.states.boto_apigateway.absent(name, api_name, stage_name, nuke_api=False, region=None, key=None, keyid=None, profile=None)

  Ensure the stage_name associated with the given api_name deployed by boto_apigateway's present state is removed. If the currently associated deployment to the given stage_name has no other stages associated with it, the deployment will also be removed.

  name

    Name of the swagger file in YAML format

  api_name

    Name of the rest api on AWS ApiGateway to ensure is absent.

  stage_name

    Name of the stage to be removed irrespective of the swagger file content. If the current deployment associated with the stage_name has no other stages associated with it, the deployment will also be removed.

  nuke_api

    If True, removes the API itself only if there are no other stages associated with any other deployments once the given stage_name is removed.

  region

    Region to connect to.

  key

    Secret key to be used.

  keyid

    Access key to be used.

  profile

    A dict with region, key and keyid, or a pillar key (string) that contains a dict with region, key and keyid.

salt.states.boto_apigateway.present(name, api_name, swagger_file, stage_name, api_key_required, lambda_integration_role, lambda_region=None, stage_variables=None, region=None, key=None, keyid=None, profile=None, lambda_funcname_format='{stage}_{api}_{resource}_{method}', authorization_type='NONE', error_response_template=None, response_template=None)

  Ensure the spcified api_name with the corresponding swaggerfile is deployed to the given stage_name in AWS ApiGateway.

  this state currently only supports ApiGateway integration with AWS Lambda, and CORS support is handled through a Mock integration.

  There may be multiple deployments for the API object, each deployment is tagged with a description (i.e. unique label) in pretty printed json format consisting of the following key/values.

      {
          "api_name": api_name,
          "swagger_file": basename_of_swagger_file
          "swagger_file_md5sum": md5sum_of_swagger_file,
          "swagger_info_object": info_object_content_in_swagger_file
      }

  Please note that the name of the lambda function to be integrated will be derived via the provided lambda_funcname_format parameters:

  - the default lambda_funcname_format is a string with the following substitutable keys: "{stage}_{api}_{resource}_{method}". The user can choose to reorder the known keys.

  - the stage key corresponds to the stage_name passed in.

  - the api key corresponds to the api_name passed in.

  - the resource corresponds to the resource path defined in the passed swagger file.

  - the method corresponds to the method for a resource path defined in the passed swagger file.

  For the default lambda_funcname_format, given the following input:

      api_name = '  Test    Service'
      stage_name = 'alpha'
      basePath = '/api'
      path = '/a/{b}/c'
      method = 'POST'

  We will end up with the following Lambda Function Name that will be looked up: 'test_service_alpha_a_b_c_post'

  The canconicalization of these input parameters is done in the following order:

  1. lambda_funcname_format is formatted with the input parameters as passed,

  2. resulting string is stripped for leading/trailing spaces,

  3. path parameter's curly braces are removed from the resource path,

  4. consecutive spaces and forward slashes in the paths are replaced with '_'

  5. consecutive '_' are replaced with '_'

  Please note that for error response handling, the swagger file must have an error response model with the following schema. The lambda functions should throw exceptions for any non successful responses. An optional pattern field can be specified in errorMessage field to aid the response mapping from Lambda to the proper error return status codes.

      Error:
        type: object
        properties:
          stackTrace:
            type: array
            items:
              type: array
              items:
                type: string
            description: call stack
        errorType:
          type: string
          description: error type
        errorMessage:
          type: string
          description: |
            Error message, will be matched based on pattern.
            If no pattern is specified, the default pattern used for response mapping will be +*.

  name

    The name of the state definition

  api_name

    The name of the rest api that we want to ensure exists in AWS API Gateway

  swagger_file

    Name of the location of the swagger rest api definition file in YAML format.

  stage_name

    Name of the stage we want to be associated with the given api_name and swagger_file definition

  api_key_required

    True or False - whether the API Key is required to call API methods

  lambda_integration_role

    The name or ARN of the IAM role that the AWS ApiGateway assumes when it executes your lambda function to handle incoming requests

  lambda_region

    The region where we expect to find the lambda functions. This is used to determine the region where we should look for the Lambda Function for integration purposes. The region determination is based on the following priority:

    1. lambda_region as passed in (is not None)

    2. if lambda_region is None, use the region as if a boto_lambda function were executed without explicitly specifying lambda region.

    3. if region determined in (2) is different than the region used by boto_apigateway functions, a final lookup will be attempted using the boto_apigateway region.

  stage_variables

    A dict with variables and their values, or a pillar key (string) that contains a dict with variables and their values. key and values in the dict must be strings. {'string': 'string'}

  region

    Region to connect to.

  key

    Secret key to be used.

  keyid

    Access key to be used.

  profile

    A dict with region, key and keyid, or a pillar key (string) that contains a dict with region, key and keyid.

  lambda_funcname_format

    Please review the earlier example for the usage. The only substituable keys in the funcname format are {stage}, {api}, {resource}, {method}. Any other keys or positional substitution parameters will be flagged as an invalid input.

  authorization_type

    This field can be either 'NONE', or 'AWS_IAM'. This will be applied to all methods in the given swagger spec file. Default is set to 'NONE'

  error_response_template

    String value that defines the response template mapping that should be applied in cases error occurs. Refer to AWS documentation for details: http://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-mapping-template-reference.html

    If set to None, the following default value is used:

        '#set($inputRoot = $input.path('$'))\n'
        '{\n'
        '  "errorMessage" : "$inputRoot.errorMessage",\n'
        '  "errorType" : "$inputRoot.errorType",\n'
        '  "stackTrace" : [\n'
        '#foreach($stackTrace in $inputRoot.stackTrace)\n'
        '    [\n'
        '#foreach($elem in $stackTrace)\n'
        '      "$elem"\n'
        '#if($foreach.hasNext),#end\n'
        '#end\n'
        '    ]\n'
        '#if($foreach.hasNext),#end\n'
        '#end\n'
        '  ]\n'

    Added in version 2017.7.0.

  response_template

    String value that defines the response template mapping applied in case of success (including OPTIONS method) If set to None, empty ({}) template is assumed, which will transfer response from the lambda function as is.

    Added in version 2017.7.0.

salt.states.boto_apigateway.usage_plan_absent(name, plan_name, region=None, key=None, keyid=None, profile=None)

  Ensures usage plan identified by name is no longer present

  Added in version 2017.7.0.

  name

    name of the state

  plan_name

    name of the plan to remove

      usage plan absent:
        boto_apigateway.usage_plan_absent:
          - plan_name: my_usage_plan
          - profile: my_profile

salt.states.boto_apigateway.usage_plan_association_absent(name, plan_name, api_stages, region=None, key=None, keyid=None, profile=None)

  Ensures usage plan identified by name is removed from provided api_stages If a plan is associated to stages not listed in api_stages parameter, those associations remain intact.

  Added in version 2017.7.0.

  name

    name of the state

  plan_name

    name of the plan to use

  api_stages

    list of dictionaries, where each dictionary consists of the following keys:

    apiId

      apiId of the api to detach usage plan from

    stage

      stage name of the api to detach usage plan from

      UsagePlanAssociationAbsent:
        boto_apigateway.usage_plan_association_absent:
          - plan_name: my_plan
          - api_stages:
            - apiId: 9kb0404ec0
              stage: my_stage
            - apiId: l9v7o2aj90
              stage: my_stage
          - profile: my_profile

salt.states.boto_apigateway.usage_plan_association_present(name, plan_name, api_stages, region=None, key=None, keyid=None, profile=None)

  Ensures usage plan identified by name is added to provided api_stages

  Added in version 2017.7.0.

  name

    name of the state

  plan_name

    name of the plan to use

  api_stages

    list of dictionaries, where each dictionary consists of the following keys:

    apiId

      apiId of the api to attach usage plan to

    stage

      stage name of the api to attach usage plan to

      UsagePlanAssociationPresent:
        boto_apigateway.usage_plan_association_present:
          - plan_name: my_plan
          - api_stages:
            - apiId: 9kb0404ec0
              stage: my_stage
            - apiId: l9v7o2aj90
              stage: my_stage
          - profile: my_profile

salt.states.boto_apigateway.usage_plan_present(name, plan_name, description=None, throttle=None, quota=None, region=None, key=None, keyid=None, profile=None)

  Ensure the spcifieda usage plan with the corresponding metrics is deployed

  Added in version 2017.7.0.

  name

    name of the state

  plan_name

    [Required] name of the usage plan

  throttle

    [Optional] throttling parameters expressed as a dictionary. If provided, at least one of the throttling parameters must be present

    rateLimit

      rate per second at which capacity bucket is populated

    burstLimit

      maximum rate allowed

  quota

    [Optional] quota on the number of api calls permitted by the plan. If provided, limit and period must be present

    limit

      [Required] number of calls permitted per quota period

    offset

      [Optional] number of calls to be subtracted from the limit at the beginning of the period

    period

      [Required] period to which quota applies. Must be DAY, WEEK or MONTH

      UsagePlanPresent:
        boto_apigateway.usage_plan_present:
          - plan_name: my_usage_plan
          - throttle:
              rateLimit: 70
              burstLimit: 100
          - quota:
              limit: 1000
              offset: 0
              period: DAY
          - profile: my_profile