AWS Serverless Application Model (SAM) -- How do I change StageName?

Question

I'm using AWS SAM (Serverless Application Model) to create a lambda with an API endpoint.

In my SAM template.yaml I have a getUser lambda with a /user endpoint.

template.yaml

Resources:
  GetUser:
    Type: AWS::Serverless::Function
    Properties:
      CodeUri: ./src
      Handler: handler.getUser
      Timeout: 300
      Runtime: nodejs6.10
      Events:
        GetUser:
          Type: Api
          Properties:
            Path: /user
            Method: get

When I deploy this using AWS CLI it successfully creates the lambda and endpoint, but with an API Gateway Stage confusingly named "Stage". I want to change stage name to something else, like "Prod". How do I change stage name?

Here's where stage name is defined in the cloudformation template after it is deployed. I want "StageName": "Stage" to be something like "StageName": "Prod".

"ServerlessRestApiDeployment": {
  "Type": "AWS::ApiGateway::Deployment",
  "Properties": {
    "RestApiId": {
      "Ref": "ServerlessRestApi"
    },
    "StageName": "Stage"
  }

Answer 1

I haven't been able to remove the Stage StageName, but when I deploy using SAM, I set a dynamic StageName in my GatewayAPI deployment using:

Properties: StageName: !Ref "STAGE_VARIABLE"

I have a different stack for each environment, so there is a prod API with a prod stage and a dev API with a dev stage. I found this easier than have multiple stage deployments of the same GatewayAPI

Answer 2

To add another stage to an existing API, use a vanilla CFT stage resource. Docs are here: https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-stage.html A transform modifies the API to raw CFTs before deployment when using the SAM CLI, but it supports raw resources and you can reference the dynamic deployment resource using a .Deployment suffix. You should be able to just add the resource and reference your API values via the ref intrinsic. Check out the details here: https://github.com/awslabs/serverless-application-model/blob/master/versions/2016-10-31.md#awsserverlessapi

# assuming there is a AWS::Serverless::Api resource named Api
ProdApiStage:
    Type: AWS::ApiGateway::Stage
    Properties:
      StageName: prod
      RestApiId: !Ref Api
      DeploymentId: !Ref Api.Deployment

There was a bug in the SAM CLI that autogenerated a "Stage" stage. To remove the default generated "stage" stage, upgrade your sam cli to the latest, and add a globals section setting the openapi version:

Globals:
  Api:
    OpenApiVersion: 3.0.1

See https://github.com/awslabs/serverless-application-model/issues/191 for the details. This will prevent new spawns, but you will have to delete the stage manually if it was already deployed as SAM is stateless in nature.