Sample CloudFormation Stack
This directory provides a set of AWS CloudFormation templates to automatically build and deploy a demo site with the Lex web interface from this project. The templates can be used to create and manage associated resources such as the Lex Bot and Cognito Identity Pool.
By default, the web application is bootstrapped from source files hosted in an AWS owned S3 bucket (see below for instructions on hosting your own). Once deployed, the CloudFormation stack outputs links to resources including the sample site and iframe embedding instructions.
There are two master CloudFormation templates used for two different deployment modes:
- CodeBuild Mode configures and deploys
directly to S3 from a CodeBuild project. It is deployed using he
master.yaml template. This mode uses the pre-built
version of the chatbot UI library in the
distdirectory at the root of this repository. By using the pre-built library, this makes this mode faster and simpler to manage - Pipeline Mode configures, builds and deploys using a CI/CD pipeline (CodeCommit, CodeBuild and CodePipeline). It is deployed using the master-pipeline.yaml template. This mode creates an automated deployment pipeline that performs a full build of the application from source. This mode provides finer customization and the ability to automatically push your own changes by committing to your code repository
To launch a stack using the CodeBuild Mode (faster and easier), click this button:
Click the following button to launch a stack using the Pipeline Mode:
The CloudFormation stack can create resources in your AWS account including:
- Amazon Lex bot. You can optionally pass the bot name of an existing one to avoid creating a new one.
- Cognito Identity Pool used to pass temporary AWS credentials to the web app. You can optionally pass the ID of an existing Cognito Identity Pool to avoid creating a new one.
- CodeBuild project to configure and deploy to S3 when using the CodeBuild Deployment Mode. If using the Pipeline Deployment Mode, a CodeBuild project is created to bootstrap a CodeCommit repository whit the application source.
- S3 buckets to host the web application and to store build artifacts.
- Lambda functions used as CloudFormation Custom Resources to facilitate custom provisioning logic
- CloudWatch Logs groups automatically created to log the output of Lambda the functions
- Associated IAM roles for the stack resources
If using the Pipeline Deployment Mode, the stack also creates the following resources:
- CodeCommit repository loaded with the source code in this project. This is only created when using the pipeline deployment mode
- A continuous delivery pipeline using CodePipeline and CodeBuild. The pipeline automatically builds and deploys changes to the app committed to the CodeCommit repo
The following table lists the CloudFormation templates used to create the stacks:
| Template | Description |
|---|---|
| master.yaml | This is the master template used to deploy the stack using the CodeBuild Mode |
| master-pipeline.yaml | This is the master template used to deploy the stack using the Pipeline Mode |
| lexbot.yaml | Lex bot and associated resources (i.e. intents and slot types). |
| cognito.yaml | Cognito Identity Pool and IAM role for unauthenticated identity access. |
| codebuild-deploy.yaml | Uses CodeBuild to create a configuration and deploy it along the site to S3. Used in CodeBuild Mode |
| coderepo.yaml | CodeCommit repo dynamically initialized with the files in this repo using CodeBuild and a custom resource. Used in Pipeline Mode |
| pipeline.yaml | Continuous deployment pipeline of the Lex Web UI Application using CodePipeline and CodeBuild. The pipeline takes the source from CodeCommit, builds the Lex web UI application using CodeBuild and deploys the app to an S3 bucket. Used in Pipeline Mode |
When launching the stack, you will see a list of available parameters and a brief explanation of each one. You can take the default values of all the CloudFormation parameters when you want to quickly test the sample application. If you are deploying your own bot and/or integrating with an existing page, you may want to modify the following parameters:
BotName: Name of pre-existing Lex bot. This is an optional parameter. If left empty, a sample bot will be created based on the OrderFlowers bot in the Lex Getting Started documentation.CognitoIdentityPoolId: Id of an existing Cognito Identity Pool. This is an optional parameter. If left empty, a Cognito Identity Pool will be automatically created. The pool ID is used by the web ui to get AWS credentials for making calls to Lex and Polly.ParentOrigin: Origin of the parent window. Only needed if you wish to embed the web app into an existing site using an iframe. The origin is used to control which sites can communicate with the iframe
NOTE: Some parameters should be unique per AWS region. The parameter descriptions specify when that is the case.
When deploying using the CodeBuild Mode, you can pass some of the most commonly changed chatbot UI configuration by using CloudFormation parameters. This includes the following parameters:
WebAppConfBotInitialText: First bot message displayed in the chatbot UIWebAppConfBotInitialSpeech: Message spoken by bot when the microphone is first pressed in a conversationWebAppConfToolbarTitle: Title displayed in the chatbot UI toobar
Once the CloudFormation stack is successfully launched, the status of
all nested stacks will be in the CREATE_COMPLETE green status. At
this point, the master stack will reference the resources in the output
section.
NOTE: When deploying with the Pipeline
Mode, the web app links will be available
once the pipeline has completed deploying (this process can take a
while). See the PipelineUrl output link to monitor the deployment
process. Similarly, in CodeBuild Mode
there may be a small delay before the links are available. In this mode,
you can monitor the build progress by browsing to the CodeBuildUrl
output variable.
Here is a list of the most relevant output variables:
WebAppUrl: URL of the web app running on a full pageParentPageUrl: URL of the web app running in an iframe. This is an optional output that is returned only when the stack creates the sample site It is not returned if an existing origin is passed as a parameter to the stack during creationSnippetUrl: URL of a simple page showing the config created by the build process and a HTML snippet demonstrating how to load the chatbot UI in an iframe based on the configCognitoIdentityPoolId: Pool ID of the Cognito Identity Pool created by the stack. This is an optional output that is returned only when the stack creates a Cognito Identity Pool. It is not returned if an existing pool ID was passed as a parameter to the stack during creation.BotName: Name of the Lex bot created by the stack. This is an optional output that is returned only when the stack creates the sample Lex bot. It is not returned if an existing Bot was passed as a parameter to the stack during creation
This output variable is specific to the CodeBuild Mode:
CodeBuildUrl: Link to CodeBuild project in the AWS console. After the stack is successfully launched, the build is automatically started. You can click on this link to monitor the build progress
These output variables are specific to the Pipeline Mode:
PipelineUrl: Link to CodePipeline in the AWS console. After the stack is successfully launched, the pipeline automatically starts the build and deployment process. You can click on this link to monitor the pipelineCodeCommitRepoUrl: When using the Pipeline Deployment Mode, this is the CodeCommit repository URL. You can clone the repo using this link and push changes to it to have the pipeline build and deploy the web app
The CloudFormation stack builds and deploys the application using CodeBuild. Various CloudFormation parameters and resource names are passed as environmental variables to CodeBuild. This includes references to the S3 Buckets, Cognito Identity Pool and Lex Bot created by CloudFormation. CodeBuild uses the Makefile in the root directory of this repository control the build and deployment process.
This is the deployment mode used by the master.yaml file. In this mode, the stack creates a CodeBuild project that creates the application configuration and deploys the files to S3.
Click the following CloudFormation button to launch your own copy of the sample application stack in the us-east-1 (N. Virginia) AWS region:
Once the CloudFormation stack is successfully launched and the status
of all nested stacks is CREATE_COMPLETE, browse to the CodeBuildUrl
link in the output section of the stack. Monitor the build run to make
sure it is successful. After the CodeBuild run completes, you can browse
to the ParentPageUrl or WebAppUrl links in the CloudFormation output
to see the deployed chatbot UI.
Once deployed, you can go back to the CodeBuild project to change the application configuration by modifying the environmental variables passed by CodeBuild. You can start a new build in CodeBuild to reconfigure and redeploy the application.
The CodeBuild project uses a zip file, passed in the BootstrapBucket
parameter, as its source (defaults to an AWS owned S3 bucket). That zip
file contains the source in this project and it is regularly updated. If
you want to use your own source, see the Deploy Using My Own Bootstrap
S3 Bucket section below.
When creating the stack with the master-pipeline.yaml template, the stack creates a deployment pipeline using CodeCommit CodePipeline and CodeBuild which automatically builds and deploys changes to the app committed to the CodeCommit repo.
Here is a diagram of the CloudFormation stack created by the pipeline deployment mode:
To deploy a CloudFormation stack with a working demo of the application, follow the steps below:
- Click the following CloudFormation button to launch your own copy of
the sample application stack in the us-east-1 (N. Virginia) AWS region:
- You can accept the defaults in the CloudFormation Create Stack Wizard
up until the last step. At the last step, when prompted to create
the stack, select the checkmark that says: "I acknowledge that AWS
CloudFormation might create IAM resources with custom names". It takes
about 10 minutes for the CloudFormation stacks to got to
CREATE_COMPLETEstatus - Once the status of all the CloudFormation stacks
is
CREATE_COMPLETE, click on thePipelineUrllink in the output section of the master stack. This will take you to the CodePipeline console. You can monitor the progress of the deployment pipeline from there. It takes about 10 minutes to build and deploy the application - Once the pipeline has deployed successfully, go back to the
output section of the master CloudFormation stack and click on the
ParentPageUrllink. You can also browse to theWebAppUrllink. Those links will take you to the sample application running as an embedded iframe or as a stand-alone web application respectively
The source of this project is automatically forked into a CodeCommit
repository created by the CloudFormation stack. Any changes pushed to
the master branch of this forked repo will automatically kick off the
pipeline which runs a CodeBuild job to build and deploy a new version
of the web app. You will need to
setup
CodeCommit to push changes to this repo. You can obtain the CodeCommit
git clone URL from the CodeCommitRepoUrl output variable of the
master stack.
Here is a diagram of the deployment pipeline:
The following files and directories are relevant to the CloudFormation setup:
.
|__ Makefile # Makefile run by CodeBuild
|__ build # contains utilities for uploading the project sources to S3
|__ config # config files used during the build
|__ lex-web-ui # sample Lex web ui application source
|__ templates # cloudformation templates and related lambda functions
|__ custom-resources # lambda functions used in cfn custom resources
The BotName CloudFormation parameter can be used to point
the stack to an existing bot. In the application, you can also
change the configuration files or pass parameters to it (see the
Configuration section of the main README
for details).
If you want to make changes to the sample bot deployed by the stack, you can edit the bot-definition.json file. This file is used by the lex-manager.py which is run in Lambda by a CloudFormation Custom Resource in the bot stack created by the lexbot.yaml template. The bot definition is in a JSON file that contains all the resources associated with the bot including intents and slot types.
The lex-manager.py script can be also used as a stand-alone shell script. It allows to export existing bots (including associated resources like intents and slot types) into a JSON file. The same script can be used to import a bot definition into an account or to recursively delete a bot and associated resources. Here is the script usage:
$ python lex-manager.py -h
usage: lex-manager.py [-h] [-i [file] | -e [botname] | -d botname]
Lex bot manager. Import, export or delete a Lex bot. Used to
import/export/delete Lex bots and associated resources (i.e. intents, slot
types).
optional arguments:
-h, --help show this help message and exit
-i [file], --import [file]
Import bot definition from file into account. Defaults
to: bot-definition.json
-e [botname], --export [botname]
Export bot definition as JSON to stdout Defaults to
reading the botname from the definition file: bot-
definition.json
-d botname, --delete botname
Deletes the bot passed as argument and its associated
resources.
The resources created by this stack can be easily removed from your account by deleting the master CloudFormation stack. The master stack is the one that was first created using the "Launch Stack" button. By deleting this stack, the rest of the sub-stacks and resources will be deleted with the exception of the CloudWatch Logs groups created by the stack (these are retained for troubleshooting purposes).
The S3 buckets created by the stacks are deleted by default. If you wish
to retain the data in these buckets, you should set the CleanupBuckets
parameter to false in the master stack.
By default, the CloudFormation stacks use pre-staged files from an AWS owned S3 bucket. These files are dynamically downloaded by the CodeBuild project created by the CloudFormation stack and copied to S3 buckets created in your account. Additionally, these files are used to bootstrap the CodeCommit repo used as the CodePipeline source when using the Pipeline Deployment Mode.
The bootstrap bucket name and prefix are controlled by the
BootstrapBucket and BootstrapPrefix parameters of the master
CloudFormation templates. If you want to use your own bootstrap S3
bucket, this project provides a Makefile under the build directory
to facilitate uploading the bootstrap artifacts. Follow these steps to
populate the S3 bucket:
- Create your own S3 bucket (you might want to enable bucket versioning on this bucket).
- Modify the variables in the local build environment file:
config/env.mk. These variables control the build
environment and web application deployment. In specific, you should
modify the following variables:
BOOTSTRAP_BUCKET_PATH: point it to your own bucket (step 1) and prefix merged together as the path to the artifacts
- Upload the files to your S3 bucket using
make uploadfrom the build directory under the root of the repo. This directory contains aMakefilethat can be used to build the artifacts and upload the files to your S3 bucket. It uses the aws cli to copy the files to S3 - Deploy the stack by using the
master.ymlormaster-pipelinetemplates. Change the theBootstrapBucketandBootstrapPrefixparameters to point to your own bucket and path