Skip to content

Home

Jump to bottom
Ben Leggett edited this page May 14, 2019 · 144 revisions

Overview

This page describes the steps required for installing the Jazz framework, using the Jazz Installer. For more details on the Jazz Serverless Development Framework, please refer here.

Prerequisites

  • Installer box: Installer box that brings up the Jazz stack.

    • You can use a CentOS (7.x) instance as your installer box. To create a new CentOS instance please refer here.

  • AWS account: Installation will deploy the platform components as well as create user services in AWS.

Ensure you have the IAM keys with sufficient permissions to create the following AWS resources in us-east-1/us-west-2:

AWS::ApiGateway
AWS::CloudFormation
AWS::CloudFront
AWS::Cognito
AWS::DynamoDB    
AWS::ECR
AWS::Elasticsearch
AWS::IAM::Policy
AWS::Kinesis
AWS::Lambda
AWS::S3::Bucket

Note that not all AWS regions support all of these AWS resources yet, and if you pick a region that lacks support for one or more of these resource types, the installer will fail. Refer to the AWS offical region table for an up-to-date listing. The installer has been tested in the following regions:

  • us-east-1
  • us-west-2

A list of the resources the Terraform installer will create can be found here, though running terraform plan will provide a more detailed and accurate listing.

Scenarios

Install

Ensure that you have a standard install of Python 3.6 or greater, with pip and setuptools

NOTE: If you want to use the SCM(Gitlab) and CI system(Jenkins) instances the installer sets up for you, then no additional steps are required. If you wish to "bring your own" SCM and CI instances, please verify you have completed all the Additional Prerequisites for Existing Instances steps first.

  1. If have not already SSH'ed into to the installer box that you set up here, do so.

1(a). (Optional) Export your AWSCLI credentials as environment variables if you have not already done so. If the credentials are not detected in the environment you will be asked for them later:

    export AWS_ACCESS_KEY_ID=<YOUR_ACCESS_KEY>
    export AWS_SECRET_ACCESS_KEY=<YOUR_SECRET_KEY>
  1. Run the below commands to start the installation. This will set up a Python3 virtual env and install the required packages.
git clone https://github.com/tmobile/jazz-installer.git
cd jazz-installer
python3 -m virtualenv env && source env/bin/activate
pip install -r requirements.txt
python Installer.py install --stackprefix myteststack --adminemail test@tst.com --region us-east-1 scenario3

NOTE: If you are looking to enable optional features like code quality, use the command listed here:

NOTE: If you want to install a specific version of Jazz, or the latest develop version, simply: a. Clone the correct installer branch (e.g. for version 1.7): git clone --branch 1.7 https://github.com/tmobile/jazz-installer.git b. Instruct the installer script to use the matching branch when installing the Jazz core: python Installer.py install --branch 1.7 <other_args> scenario3

  1. Follow the installer wizard prompts:

    1. You will be asked to provide a prefix for your stack (Please use only lowercase alphabets & numbers for tag name. Some of the artifacts are named using this information and AWS has restrictions on how we use this tag. DO NOT run the installer on top of an existing installation without first destroying the existing installation).

    2. You will be asked to provide an admin email address that will be used to manage Jazz.

  2. Once the installation is complete, you should see a log similar to this:

Please use the following values for checking out Jazz
 ________________________________________________
{
     "Jenkins ELB" : "{Jenkins Host Name}",
     "Jenkins Username" : "{Jenkins User Name}",
     "Jenkins Password" : "{Jenkins Password}",
     "Jazz Home" : "{Jazz Home Page}",
     "Jazz Admin Username" : "{Jazz Admin Email Address you provided}",
     "Jazz Admin Password" : "{Jazz Admin Password that was autogenerated for you}",
     ...
}

You can also run tail -20 stack_creation.out inside the jazz-installer directory to find the details to administer Jazz.

Follow the post-install steps covered here before starting to use Jazz.

Limitations

  • Current version runs only on AWS Stack.

  • From Jazz version > v1.12, installer deploys docker containers (related to internal Jazz components) to ECS Fargate service. Currently, you may run into disk space errors because of underlying issue with ECS Fargate (Has a disk space limit of 10GB as described here. AWS is working on related features according to their roadmap. We'll implement changes that can potentially resolve these issues as soon as related features are available in AWS Fargate.

  • Note: To resolve disk space issue in Jenkins, Go to Jenkins script console (JenkinsURL/script) and run the below code snippet

    def sout = new StringBuilder(), serr = new StringBuilder()
def proc = 'rm -rf /var/jenkins_home/workspace/jazz_ui/jazz_ui '.execute()
def list = ["build_modules","jazz_admin","jazz_assets","jazz_codeq","jazz_create-serverless-service","jazz_delete- serverless-service","jazz_deployments","jazz_email","jazz_environments","jazz_events","jazz_is-service-available","jazz_is-slack-channel-available","jazz_login","jazz_logout","jazz_logs","jazz_metrics","jazz_scm-webhook","jazz_services","jazz_slack-channel","jazz_test-lambda","jazz_usermanagement"]
for (item in list) {
   proc = "rm -rf /var/jenkins_home/workspace/build-pack-api/$item".execute()
}
proc.consumeProcessOutput(sout, serr)
proc.waitForOrKill(1000)
if (serr) {
  println "error > $serr"
} else {
  println "done > $sout"
}
Clone this wiki locally