@loandolphin/jose-bot v1.0.3

Meet JoSe 🤖

JoSe - Joust Serverless, is a bot to manage Joust Serverless applications. It was built to optimise management and repeating tasks, such as deployments, saving development time and possible some configuration headaches as well 😅

Requirements

There are a few requirements to use Jose:

• Install AWS CLI tool (instructions here);
• Install AWS SAM CLI tool (instructions here);
• Configure our AWS Credentials using AWS CLI (instructions here);
• Install @loandolphin/jose-bot npm package globally.

We recommend you to install JoSe globally, so you can take advantage of the command lines on your Serverless projects. The NPM package is available on: http://npmjs.com/.

You just need to run the command below and install it globally:

⇒ npm install -g @loandolphin/jose-bot

Configuring Your Project

AWS Environment Variables

First of all, you will have to set up some basic environment variables. On your project's root folder, create a new file called .env and define the following variables:

AWS_REGION=ap-southeast-2
AWS_ACCOUNT={AWS_ACCOUNT}
AWS_DEPLOYMENT_IAM_ROLE_ARN=arn:aws:iam::{AWS_ACCOUNT}:role/JoustDeploymentRole
AWS_CLOUDFORMATION_IAM_ROLE_ARN=arn:aws:iam::{AWS_ACCOUNT}:role/JoustPassedRole

NAME={PROJECT_NAME}
ENVIRONMENT={ENVIRONMENT_NAME}
SAM_TEMPLATE_FILE_NAME=template.yaml
SAM_OUTPUT_TEMPLATE_FILE_NAME=packaged.yaml

You really need to replace the {} variables by the AWS environment target (the one that you want to deploy).

• AWS_ACCOUNT: This is the AWS account number;
• PROJECT_NAME: The project name;
• ENVIRONMENT_NAME: The AWS environment name (use to be the account name);

Generating Template Environment Variables

Ok! Now that you have configured the .env file on your project's root folder, it's time to set up your template's parameters as environment variables. JoSe can help us extracting those parameters and transforming them as environment variables on a specific template .env file.

On your terminal, execute the command:

⇒ jose-bot extract-template-variables

Extracting template variables...
Template variables have been extracted successfully.
Check out the generated file: ${project-root-folder}/.template.env

The command above will read all template's parameters and create a new file called .template.env with them. As the result, you will have a file similar to:

CONFIG_SEND_EMAIL_FEATURE_STATUS=
CONFIG_MAILER_PROVIDER_API_KEY=
CONFIG_EMAIL_FROM_ADDRESS=
CONFIG_EMAIL_FROM_NAME=

Now, you just need to include the respective values to each variable and your project is ready to be built and deployed.

Supported Commands

Currently, JoSe only supports a few commands. They are:

• Deploy
• Delete Stack

Note: To perform any command, make sure you are executing them from your project's root folder.

Deploy a Serverless Application

This command allows to deploy a Serverless application. Because you have already set up the project previously, you only need to perform the following command on your terminal:

⇒ jose-bot deploy

Then JoSe will perform all the required actions to ensure your application will be deployed to the target AWS Account configured.

Delete a AWS CloudFormation Stack

This command allows to delete an AWS CloudFormation Stack, in case you want to drop an whole environment off from AWS. Keep in mind that this operation can't undone and it will delete all application's resources, include databases and any other storage service, if it exists.

⇒ jose-bot delete-stack

Cross-Account Deployment

Your user probably does not belong to the same AWS account that you are going to work. For that reason, you will need to assume a role from the target AWS account which will be able to perform changes.

First of all, you will need to have two roles on your AWS target account: JoustDeploymentRole and JoustPassedRole. Your user should assume the JoustDeploymentRole role which will allow you to perform some basic operations, such as manage the CloudFormation, S3 and CloudFront. These permissions will allow you to upload your Lambda functions to a S3 bucket that will be consumed later on by the CloudFormation template. Here's an example of this role's permissions:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Action": [
        "iam:PassRole",
        "cloudformation:*",
        "cloudfront:*",
        "s3:*",
        "iam:CreateServiceLinkedRole",
        "apigateway:POST",
        "apigateway:PATCH"
      ],
      "Resource": "*",
      "Effect": "Allow"
    }
  ]
}

The second role is JoustPassedRole and it has administrator access to this AWS account. This role can't be assumed by your user but it's used by the JoustDeploymentRole role when deploying the application. It has a trusted entity relationship with CloudFormation which grants admin permission to create any resource defined on the template.

⇒ sam deploy {...} --role-arn $JoustPassedRole