Zappa CLI Interface about zappa

[bbangert]

In short, we define a handler function that reads an included zappa.ini file that the developer created, that indicates how to build a WSGI app object. The zappa handler will load the wsgi app as designated below on first-run, wrap it in the Zappa WSGI middleware, then cache it for later runs so the WSGI app is made only once. The zappa handler then does a normal WSGI app call into the WSGI app and returns.

We just ask the developer to tell us where their wsgi app creator function is located, and indicate how we'll call it. It's going to be custom for each framework, but we can ensure its a very very small amount of code, so it won't be a big deal.

Here's a README-driven approach...

Deploying to AWS Lambda with Zappa

Deploying your WSGI-based Python application with Zappa is easy. To get started, install Zappa:

$ pip install Zappa

Next, you will need to create a zappa.ini configuration file so that Zappa knows a few things about the structure of your application. Here is a sample file to get started with:

[zappa]
wsgi_app = myapplication.main:make_wsgi_app
settings = s3://mybucket/myconfig.ini
lambda_role = arn:....
gateway_role = arn:.....
gateway_name = mywsgiapp
gateway_prefix = /v1

# Any other hardcoded config options to be passed in...
[application]
debug = false
...

You can now upload and/or deploy your WSGI application to AWS:

$ zappa deploy --stage=dev --config=zappa.ini

WSGI Configuration

Lambda has no mechanism in place to define configuration information for its environment at deploy-time. While API Gateway provides variables for each API deployment environment, it may be preferred to pass larger sets of configuration options into your application in other ways. To facilitate this, Zappa provides a mechanism to change the configuration of already deployed Lambda functions and can include additional config in the uploaded deployment package.

Runtime Configuration

The configuration of an already deployed application can be altered if settings was defined in the INI file. Upon initial launch of your Lambda-deployed WSGI application, the designated S3 settings file will be loaded and passed into your wsgi_app function. The S3 file will be loaded anytime the Lambda runtime environment is started allowing settings to be altered without redeploying the application.

Hardcoded Configuration

Settings under [application] are passed into the wsgi_app on creation. These settings cannot be altered without re-deploying the application to AWS.

wsgi_app Function

You may need to break up your main function if using a micro-framework (Flask, Bottle, etc) or Pyramid so that the code creating the main wsgi application object is separate from running the server. Your wsgi_app function will be called with three configuration dicts reflecting configuration obtained from the API Gateway variables, your hardcoded options, and S3.

def make_wsgi_app(gateway_config, app_config, s3_config):
    # Create the wsgi app
    return my_framework_make_wsgi_app(app_config, **s3_config)

Flask Flask objects and Pyramid Configurator objects have methods on them that will return a WSGI compatible application object.

Flask Example

Many Flask applications have a package __init__.py or app.py file that sets up the Flask application object, for Zappa, all that is needed is an additional function to load/parse the configuration as desired before the Flask app instance is created. Once you have handled the configuration as desired, load and return the Flask applications WSGI app attribute.

# zappa.py

def wsgi_app(gateway_config, app_config, s3_config):
    # Parse and deal with config, set anything up as desired, then...
    from myflaskpackage import app
    return app.wsgi_app

Note that the Flask app instance is imported inside the function to avoid loading the Flask app before configuration information is processed.

Pyramid Example

Pyramid applications generally have a main function loading a Configurator object for configuring the Pyramid app from an existing project INI file that is specified when launching the application. The INI options desired for the Pyramid application should be copied into the zappa.ini under [application] for use by the Configurator.

Given a typical Pyramid init.py, a single additional function can be added to adapt Zappa's config for the main function:

# __init__.py

def main(global_config, **settings):
    """ This function returns a Pyramid WSGI application.
    """
    config = Configurator(settings=settings)
    ....
    return config.make_wsgi_app()

def zappa(gateway_config, app_config, s3_config):
    # If all the app config was hardcode in zappa.ini
    return main(None, **app_config)

Then designate the zappa function as your Zappa wsgi_app.

[Miserlou]

Okay, I've taken the ideas presented here and in the existing flask-zappa implementation and turned them into an initial version the CLI client. Check it out!

Only one configuration JSON file is necessary, so that's nice, and it seems to work nicely with Flask and pure WSGI apps, and I'm sure it would work with Pyramid in the pattern described above, but I haven't yet tested it, hopefully tomorrow.

[Nico005]

Hi @Miserlou, i have followed your article as i am trying to get my pyramid project running with zappa.
I get the following when doing : zappa deploy --stage=dev --config=zappa.ini

zappa: error: unrecognized arguments: --stage=dev --config=zappa.ini

i see there is a zappa_settings.json file should i not just edit that file?