Service Development using Jazz
You can start creating your service using the Jazz UI. If you haven't already, install the Jazz framework by following instructions here. A quick overview on the Jazz UI is available here.
- Service Types
- Service Creation
- Development Workflow
- Service Deletion
- Monitoring Build & Deployment status for the service
Today, you can create services of the following types using Jazz.
- RESTful APIs
- Functions (example: AWS Lambda, Azure functions)
- Static Websites
- Serverless Framework based applications
We plan to support custom application templates leveraging commonly used frameworks like aws sam very soon!
Refer wiki that explains how you can create a new service using Jazz UI.
- Once your service is created, you will find a link to the service (git) repository in service overview page.
- Clone the service repository.
- You will have a preloaded code template depending on your service type & runtime that you have selected. Some of the files in your template and their purposes -
- handler has the core application logic (entry point to your service)
- deployment-env.yml file has the service & deployment related configurations
-
swagger.json has the API specifications (for service type -
api) -
app folder has the static content (for service type -
static website) -
serverless.ymlfile for your application definition (for service type -custom)
- Take time & go through the template! Once you understand where and what to change, start working on your code to implement your business logic and push the changes to a feature branch. As a best practice, you should always push your changes to a feature branch. Jazz, by default, rejects any direct code push to
masterbranch. - On pushing your changes to a feature branch, a deployment workflow kicks in automatically through Jenkins that builds, deploys and notifies user with the deployment. Since Jazz creates environments automatically, your changes to the feature branch gets deployed to a dedicated development environment. Look for a new environment with the same name as your feature branch in service details page. This will be your dedicated development environment!
- In Jazz UI, 'Deployments' section under your environment will reflect the deployment status. With a simple button click, you can retry a deployment if it fails for any reason. On a successful deployment, developer gets an email with the service endpoint details. For example, for a function in AWS, you will receive the function's ARN (Amazon Resource Name).
- Once deployment is successful, Jazz UI should show the service endpoint in the particular 'Environment' View. Remember that Jazz creates a dedicated development environment per branch! Once you see expected results for your service (say, your endpoint works!) on the development environment, you will have to submit a PR (Pull Request) to merge the changes to the master branch to deploy your changes to production environment.
To delete a service -
- In Jazz UI's service list page, locate your service and click on it to view service details.
- Delete the Service by clicking on the 'Delete Service' button.
- Jazz will kickoff a workflow that will delete the deployed service (all environments). It will also delete the code repository of the service.
You can view the deployment status using Jazz UI in 'Deployments' view for each environment. If required, you will be able to go to underlying jenkins job by clicking job id for a specific deployment in 'Deployments' view. You will also get email notifications (and/or Slack notifications if Slack is enabled by Jazz admin) related to each service deployment.
Read this before reading more about api development!
Developing an API starts with defining an API specification using swagger. The default template provides a working sample of a swagger specification to start with, defining few basic model definitions, mappings required for handling success and failure scenarios, request/response mappings, CORS header definitions for allowing cross-site origin calls etc. Swagger specification can be developed in JSON/YAML; Jazz template comes with a JSON version. A sample version of the specification is available in swagger folder.
Click here for a sample version of swagger specification that comes with the template.
Developers can modify their swagger files using swagger editor. You can load the swagger specification file by copy pasting the file content or import from a url into this editor.
Read more about swagger specification here.
Template swagger specification that Jazz provides contains few place holders (that you can ignore during your spec development) but the final version gets auto generated and gets updated based on the deployment environment during the build & deploy process. You will see following placeholder values which are usually replaced during the build process.
-
{api_deployment_node_title}- Title field in swagger that will be replaced with service name by default from the deployment configurations file. You are free to override it. -
{api_host_name}- The host field which is the endpoint where the API will be published. Each environment has different endpoint provided. This will be auto populated during the build/deployment phase. -
{domain}– This will be replaced with domain name from the deployment configuration file. Do not modify it. -
{service_name}– This will be replaced with service name from the deployment configuration file. Do not modify it.
The deployment configurations are stored in the deployment-env.yml file. This file contains metadata related to the service. Developers can use this configuration file to override few configurations (like memory assigned to the function).
-
service_id– Service ID. Do not override this! -
providerMemorySize– Memory size that you can allocate to your API (underlying function). -
providerTimeout– Timeout after which function errors out. -
region– Region where the API will be deployed. -
iamRoleARN- IAM role that your function should assume. By default, Jazz assigns a role with bare minimum permissions. If your service needs to access other AWS services (like AWS DynamoDB, AWS KMS etc.), you have to create a custom IAM role with the desired permissions and provide the ARN here. -
artifact– (Specific to java) Should be same as the artifact name given in the maven config file -pom.xml. -
mainClass– (Specific to java) Should be the name of the main Handler class.
Templates for both api and function service types come with sample unit test cases (available in the test folder) to enable TDD. Developers should extend it and add more unit test cases based on their specific business scenarios. NodeJs uses mocha with chai as the unit testing framework. Java uses JUnit and python uses pytest in Jazz environments.
All unit test cases will be run during build process and build workflow aborts when there are failed test cases. Build logs (Jenkins) should provide more details on failed test cases.
Basic sanity checks and configuration validations happen during the CI/CD workflow. deployment-env.yml file will be checked for invalid deployment configurations and swagger.json for swagger errors. Workflow fails if there are any errors. You can use swagger editor to validate your swagger.
Based on the runtime, Jazz uses different tools for code analysis. JSHint (ESLint coming soon), PEP 8, checkstyle will be used for NodeJs, Python & Java respectively.
Jazz templates come with logger utilities that does custom logging so that the platform captures logs correctly and pushes them to log management solutions like ElasticSearch or Splunk. AWS APIGateway and AWS Lambda functions write these logs to AWS CloudWatch service which are then pushed to Jazz managed ElasticSearch service (or Splunk if enabled). Java templates use Log4j, NodeJs and Python services use custom loggers in the templates. All templates follow common logging format for Jazz to parse and push them to the managed log engine.
Log format: {TIMESTAMP} {REQUEST_ID} {LOG_LEVEL} {CLASS/FUNCTION:LINE NUMBER} {LOG_MESSAGE}
Example: 2017-04-07T00:01:39 5faf8e67-1b25-11e7-80c2-05b982578e1a INFO RequestHandler:31 Hello! you have logged this message
Read this before reading more about function development!
Services of type function have the same build/deployment process and template structure similar to api services except for the swagger specification. All other configurations and process explained above will be applicable for this service type as well.
After successful deployment, Jazz UI will display the endpoint (ARN) of the function (lambda) under each environment.
Read this before reading more about static website development!
Jazz provides a simple template when developers create static websites. Developers can choose one of the supported frameworks like angular,react in Jazz UI (Other frameworks can be used but the build task will be skipped by Jazz in this case, it simply uploads the content in app folder to the cloud). Developers need to (git) push the website content into the app folder. Jazz takes care of building the website (for supported frameworks), uploading the static content to cloud services (like Amazon S3), configure CDN (like Amazon CloudFront) if user opts in and updates other applicable configurations.
The static website template contains these two files/folders -
-
deployment-env.ymlcontainsservice_idand few other configuration values that Jazz might need during deployment. -
appfolder contains static content - html, css, js, images, fonts etc. This folder should contain index.html file that would be the home page of your website.
After successful deployment, Jazz UI will display the endpoint (Amazon CloudFront endpoint, for example) for each environment.
Read this for details.