README.rst

Lizzy

Lizzy is a wrapper around Senza: a command line deployment tool for creating and executing AWS CloudFormation templates. With Lizzy, autonomous teams can use Senza, within their continuous delivery pipelines, to deploy new versions of their apps to a team-specific AWS account. Lizzy can be deployed to an AWS account, then it's REST API can be used to deploy new apps to that account.

Why Lizzy

At Zalando, development teams have their own AWS accounts so they can work autonomously. One team (Continuous Delivery) is responsible for maintaining the Jenkinses of all other Zalando teams. This allows teams to focus on their OKR's instead of spending their time configuring Jenkins or creating their own continuous deployment tools. For Zalando, Lizzy helps make continuous delivery using our Jenkins-as-a-Service setup possible. Without Lizzy teams would need to save AWS credentials to their Jenkins instance.

If your team is interested in working with immutable stacks on AWS you can use Senza to create and manage your stacks using CloudFormation. Lizzy is an additional tool that provides a deployment API to be used by your continuous delivery pipeline to run Senza commands. Lizzy can be used along with any code integration tool like Jenkins, TravisCI, CircleCI, etc.

How Lizzy Works

Lizzy consists of the Lizzy Agent — a REST API service — and the Lizzy-Client command line tool.

The Lizzy Agent is a web application deployed in a team's AWS account and granted access to create new CloudFormation stacks through a REST API. All requests are authenticated using OAuth2 bearer tokens.

Lizzy-Client mimics the usage of Senza's commands and transforms them into HTTP requests, which are then sent to Lizzy Agent's REST API.

Who Uses Lizzy

Many Zalando teams use Lizzy in production to deliver high-quality services that power the fastest-growing online fashion platform in Europe. If you want to know more about how Zalando uses Lizzy, please read our blog post Continuous Delivery pipelines of ghe-backups with Lizzy.

How to Run Lizzy Locally

This repository includes a Dockerfile that you can use to build an image locally using the command:

$ docker build -t lizzy:dev .

Hint

If you clone this repository, the "scm-source.json" file will be missing. To know more about what is in this file, please read the STUPS documentation. We have tools that can generate this file for you.

After the image is built, it will be available with the tag "lizzy:dev". You will also need to specify some environment variables for Lizzy to use. Here is an "example.cfg" file:

TOKEN_URL=https://token.auth.example.com/oauth2/access_token
TOKENINFO_URL=https://info.auth.example.com/oauth2/tokeninfo
ALLOWED_USERS=['robotusername','myusername']
DEPLOYER_SCOPE=deployer
LOG_LEVEL=DEBUG

You also need to configure the AWS credentials locally in your machine under ~/.aws. After that, you can run the Lizzy image with the command:

$ docker run --rm -p 8080:8080 --env-file environment.cfg -v ~/.aws:/.aws --name lizzy -u 999 -it lizzy:dev

The application will be available by default at the port 8080, which is usually accessible at http://127.0.0.1:8080. It depends on how you've configured Docker locally. A Swagger/OpenAPI console is available at http://127.0.0.1:8080/api/ui/#/default.

Deploying to AWS

There are many ways to deploy Lizzy to AWS. At Zalando we use STUPS, which provides a convenient and audit-compliant Platform-as-a-Service (PaaS). An example of the Senza definition to deploy Lizzy:

SenzaInfo:
  StackName: lizzy
  Parameters:
    - ImageVersion:
        Description: "Docker image version of lizzy."
SenzaComponents:
  - Configuration:
      Type: 'Senza::StupsAutoConfiguration'
  - AppServer:
      Type: Senza::TaupageAutoScalingGroup
      AssociatePublicIpAddress: false
      ElasticLoadBalancer: AppLoadBalancer
      IamRoles: ['app-lizzy']
      InstanceType: t2.nano
      SecurityGroups: ['app-lizzy']
      TaupageConfig:
        application_version: '{{Arguments.ImageVersion}}'
        environment:
          ALLOWED_USER_PATTERN: "^(jenkins-slave-\\w+)$"
          DEPLOYER_SCOPE: myscope
          LANG: C.UTF-8
          LC_ALL: C.UTF-8
          LOG_LEVEL: DEBUG
          REGION: '{{AccountInfo.Region}}'
          TOKEN_URL: 'https://token.auth.example.com/oauth2/access_token'
          TOKENINFO_URL: 'https://info.auth.example.com/oauth2/tokeninfo'
        health_check_path: /api/swagger.json
        ports: {8080: 8080}
        runtime: Docker
        source: 'lizzy:{{Arguments.ImageVersion}}'
  - AppLoadBalancer:
      HTTPPort: 8080
      HealthCheckPath: /api/swagger.json
      Scheme: internet-facing
      SecurityGroups: ['app-lizzy-lb']
      Type: Senza::WeightedDnsElasticLoadBalancer

Access Control for Lizzy

To create new CloudFormation stacks, Lizzy applications need access to CloudFormation plus some other services from Amazon's API. You will need to specify the IAM role in a manner like:

{
    "Statement": [
        {
            "Action": [
                "iam:*",
                "cloudformation:*",
                "ec2:*",
                "route53:*",
                "elasticloadbalancing:*",
                "cloudwatch:*",
                "elasticache:*",
                "acm:*",
                "autoscaling:*",
                "sqs:*"
            ],
            "Effect": "Allow",
            "Resource": "*"
        }
    ],
    "Version": "2012-10-17"
}

That is the minimal configuration Lizzy needs to run Senza commands successfully. Other statements might be included in this configuration.

Configuration

Lizzy uses the following environment variables for configuration:

NAME	DESCRIPTION	DEFAULT
ALLOWED_USERS	List of users that can use Lizzy
ALLOWED_USER_PATTERN	Defines a regular expression to match usernames allowed to use Lizzy
DEPLOYER_SCOPE	OAUTH scope needed to deploy
LOG_LEVEL	Sets the minimum log level	INFO
LOG_FORMAT	Sets the log format (human or default)	default
REGION	AWS Region to use	eu-west-1
SENTRY_DSN	Sentry URL with client keys
TOKEN_URL	URL to get a new token
TOKENINFO_URL	URL to validate the token

Configuring Access to Lizzy

There are two environment variables for configuring who is allowed to perform successful calls to the Lizzy Agent. You must use one (and ONLY one) of them: Either ALLOWED_USERS or ALLOWED_USER_PATTERN. To choose which one fits your use case, you first need to understand what they do.

• ALLOWED_USERS: List of specific usernames that can access Lizzy. Use it when you know the exact usernames of the clients you want to give access to your service.
• ALLOWED_USER_PATTERN: Regular expression that should match the username of the clients that are going to call the Lizzy API. Use it when you know that the username should start with some pattern, like stups_.+.

Those variables are mutually exclusive. Again: use only one of them.

Authentication Service

The TOKEN_URL environment variable should point to the service that provides OAuth tokens. At Zalando, we use the open-source PlanB provider for that. The TOKENINFO_URL environment variable should point to the service that stores information about the tokens. To store the OAuth2 token information, we use PlanB token info, also developed by Zalando. If you do not have any OAuth2 infrastructure, please take a look at those projects.

Contributing to Lizzy

We welcome your ideas, issues, and pull requests. Just follow the usual/standard GitHub practices.

License

Copyright 2015 Zalando SE

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.