Atmosphere Project Contribution Guide

This guide is intended to orient community members who are interested in contributing to Atmosphere -- learn about our development process, our technology stack, and our release strategy. Welcome to the project!

This page has a couple of broken links, having recently been migrated from an internal wiki -- they will be fixed soon once the linked content is migrated to atmosphere-guides.

What is Atmosphere?

Atmosphere or 'atmo' can refer to several different things:

  • Atmosphere(0), CyVerse's "cloud computing for scientists" service
  • Atmosphere(1), the free, open-source software project which powers the above service (and is the primary focus of these guides)
  • Atmosphere(2), the API and back-end component of the above software project

For clarity, this page will disambiguate all uses of "Atmosphere".

What are the steps to contributing to Atmosphere/Core services?

Contribution to core-services products (usually) takes place in two different environments:

  1. JIRA - This is an external service where we document bugs, issues, and new features to be fixed.
  2. Github - This is where our codebase generally resides. See Where is the code for more details.

The Atmosphere workflow for JIRA tickets

  1. Issues/Bugs/New Features that are found in the wild, during requirements gathering, etc. should be created as "JIRA Tickets" and assigned a fixVersion of Release Backlog or Product Backlog.
    1. JIRA Operations-note: At this time the form only lets you set affectedVersion, which is not quite the same. We should make this easier for specific users (if the workflow allows for it)
  2. JIRA Sprints and the Agile Board
    1. Tickets are assigned to match with the Release and Sprint Schedule:
    2. Currently, core-services is on a 5 week release schedule. There are two 2-week sprints and a 1-week sprint to prepare for and release the branch to the production servers.
    3. JIRA Tickets for both 2-week sprints are regularly assigned at the beginning of each release.
      1. During the first sprint after a release, primarily 'Bug' tickets will be assigned. This is done to give time for the changes to "settle" on the beta server for a few weeks.
      2. During the second sprint, primarily "Improvements and new feature" tickets will be assigned.
    4. The third sprint, only one week long, will be split between preparing for deployment and finishing up any lingering tickets that extend past the sprint deadline.
  3. The Lifecycle of a ticket
    1. Starting work on a ticket
      1. (If applicable) Tickets will move to **Start Design** and work with the design pipeline to gather requirements (See The Design Pipeline section for more details)
      2. Put the ticket into "Start Progress" and start writing Code to fix the bug/create the feature. 
      3. Tests are written for any new bug to verify the failure has been fixed and for any new feature to help with QA. (See the Testing the Code section for more details)
      4. Documentation is written (See the Documenting the Code section for more details)
    2. Reviewing a ticket
      1. Ensure that the checklist for your PR template is complete before requesting review. (see below for more details)
      2. Put the ticket into "Review" step and assign to a project lead. (See Reviewing Code section for more details)
      3. Upon merge, a project lead will move the ticket to Resolved and assigned to QA for final approval/confirmation. Notes should be included that point to the new tests/documentation as appropriate.

Using github to work on an issue/bug/feature

  1. Fork the repo you intend to work on
    1. If this is your first time contributing to a core-services repository, you will want to create a new fork. Forking a repository allows you to freely experiment with changes without affecting the original project.
    2. Github's documentation for working with forks is available here.
  2. Creating a feature branch
    1. Before starting work on a new feature or bugfix, you should create a new branch. Creating branches for your work allows you to isolate your changes when they are ready for others to review. It also gives you the ability to change to another branch, to work on separate fixes or features as necessary.
  3. Submitting a Pull Request
    1. It's a good idea to make pull requests early on. A pull request represents the start of a discussion, and doesn't necessarily need to be the final, finished submission.
    2. It's also useful to remember that if you have an outstanding pull request then pushing new commits to your GitHub repo will also automatically update the pull requests.
    3. Specific to Core-services: Pull requests will be reviewed after the "Check list" in the Pull Request template has been completed, this should include new tests and documentation!
    4. GitHub's documentation for working on pull requests is available here.

Pull Request Templates

The pull request template used by core-services can be found on the github of Atmosphere or Troposphere in ./PULL_REQUEST_TEMPLATE

NOTE: Proposals for those PR templates can be found here, and can be updated prior to merge: https://github.com/cyverse/troposphere/pull/536 and https://github.com/cyverse/atmosphere/pull/250

See this article for including a pull request template in your repository: https://help.github.com/articles/creating-a-pull-request-template-for-your-repository/

Where is Atmosphere Deployed?

Atmosphere(1) is deployed at CyVerse as Atmosphere(0), but also at several other organizations known by different names:

Resources and Docs for New Contributors

Familiarize yourself with the following links and use them as a reference. (Also check out the other guides on this site!)

Where is the Code?

Repositories on Github

(Should we make this a table of repo + link + purpose?)

Key Terms

You'll hear these a lot on the Atmosphere project:

  • Instance: a Virtual Machine (VM) or "cloud computer" running on Atmosphere(0) / OpenStack.
  • Image: a disk image of a Virtual Machine (with some metadata) from which instances are created.
  • Allocation: the amount of "CPU time" that a user is allotted, measured in AUs (see below).
  • Allocation Unit (AU): "roughly equivalent to using one CPU-hour, or to using one CPU core for one hour." (source)
  • Modal: a modal window in a GUI; the Troposphere UI uses these extensively.

Technology Stack Overview

This is intended to be an orientation to the main components of Atmosphere(1), their purpose, and their supporting technologies.

Atmosphere(1)

Atmosphere(1), broadly, is a web application which supports user-friendly access to (and management of) cloud computing resources, such as virtual machines (servers/workstations) and storage volumes.

Atmosphere(1) has a "micro-services" architecture in that the back-end API is separated from the front-end UI, but all deployments to date contain all components on one operating system environment (server).

Atmosphere(2) API and Back-End

The API is written in Python using the Django web framework, backed by a PostgreSQL database. As is typical for Django applications, Atmosphere(2) interacts with its database using Django's object-relational mapper.

Things that Atmosphere(2) does:

  • Interacts with cloud provider APIs to provision resources (instances, block storage volumes)
  • Initiates Ansible playbook runs on new and redeployed instances
  • Authenticates users
  • Keeps track of user allocations

The API is apparently documented here.

Troposphere UI

Troposphere is a separate front-end for Atmosphere(1), consisting of a Django application and JavaScript "single-page application" built with the React front-end framework. Troposphere can be thought of as a JavaScript client which interacts with Atmosphere(2) via RESTful API.

Web Server

Both Atmosphere(2) and Troposphere are served by Nginx, which serves static assets directly and reverse proxies to uWSGI (etc.) for dynamically generated content.

atmosphere-ansible

atmosphere-ansible is the set of Ansible code that runs on newly provisioned cloud instances as part of the deployment process.

Subspace

Subspace is a Python project that programmatically runs Ansible playbooks; Atmosphere(2) uses it to run atmosphere-ansible.

Clank

Clank is the set of automations that deploy Atmosphere(1) and most of its components.

Clank wraps the deployment process using Ansible, but significant parts are still automated with a mix of bash scripting, makefile, and a custom Python "configure" script which generates application configuration from jinja2 templates and .ini files. Also, unlike other Ansible code that you may have seen, Clank must be run locally on the destination server, not from a remote deployment host. The future direction is to refactor this into idiomatic Ansible and remove some layers of indirection.

Monitoring and Management

These are optional integrations which are implemented for Atmosphere(0). They are not necessary for a successful Atmosphere(1) deployment.

ELK

ELK stack (Elasticsearch, Logstash, Kibana) handles logging information from Atmosphere-Ansible.

New Relic

Sentry

???

OpenStack

Atmosphere(1) is intended to be agnostic of cloud provider type, but all current deployments use OpenStack as the cloud provider back-end. OpenStack is a collection of projects which, together, provide infrastructure-as-a-service or a 'cloud'.

Remote Access Methods

Atmosphere(1) supports several means of users accessing their instances.

SSH

Users can create a secure shell to their VMs directly over the internet, authenticating either with their Atmosphere(0) credentials or with an SSH keypair. Atmosphere(1) is essentially uninvolved in this workflow, though it provides a way for users to automatically install their public SSH key on new and re-deployed instances.

Web Shell

Web Shell gets you a command line session in your browser, launched from the Troposphere UI. Web Shell uses Gate One, a web-based terminal emulator. The Gate One server creates an SSH connection to the instance and exposes that shell to the user in a web interface, proxying the SSH traffic. For Atmosphere(0), the GateOne server is known as "bob" / "atmo-proxy".

See GateOne Background for detailed design and troubleshooting information.

Web Desktop

Web Desktop gets you a graphical desktop session in your browser, launched from the Troposphere UI. Web Desktop uses NoVNC, a web-based VNC client. This is brokered through webaccess.cyverse.org.

https://github.com/cyverse/nginx_novnc_auth

https://github.com/cyverse/clank/blob/master/playbooks/utils/install_novnc_auth.yml

Future: Guacamole

Guacamole is an HTML5 remote desktop gateway which provides both a command-line shell and a graphical desktop. Guacamole is planned as a replacement for Gate One and NoVNC, though this is not implemented in production yet.

Clouds

Atmosphere(0, 1, 2) provisions virtual machines on several 'clouds' which actually host the instances and computing infrastructure. Currently, all cloud providers use OpenStack. It is also possible for Atmosphere to provide access to commodity IaaS like Amazon Web Services (AWS), though this is not currently configured.

Tools and Workflows

Common Technologies and Tools

No matter your sub-specialty, you'll work with most/all of these as a member of the Atmosphere Team.

  • Python programming language, used for Atmosphere(2), Ansible, Subspace
  • Ansible, used for configuration management and infrastructure automation
  • YAML markup language, used for Ansible code and variables files
  • Markdown markup language, used for documentation
  • SSH, used for remotely accessing servers
  • git and Github, used for source control

Local Development Environment

The local development environment-in-a-box is not yet published for community consumption. Coming soon!

Issue Tracking Systems

The Atmosphere(0) team uses several internal systems to track development cycles and support issues. Unfortunately these are not accessible to community members. For now, please use the repository-specific Issues section in the appropriate GitHub repository (perhaps atmosphere(2)) to report an issue with Atmosphere(1,2).

If you are an Atmosphere(0) user seeking assistance and you ended up here for some reason, please log into Atmosphere and click the "Feedback & Support" link at the bottom of the page, or email support at cyverse dot org.

Contributing Code

Note that the following information may change soon as the Atmosphere(0) team refines the development process for Atmosphere(1).

On Github

Most of Atmosphere(1)'s code lives on GitHub. Contributions to these codebases should follow a fork-and-pull-request workflow.

  1. Create your own fork of the repository, work on the code there, test it in your local development environment
  2. Create a pull request
  3. Have someone else review and merge your pull request; ideally two people will review it.

Forward-facing projects that are critical to Atmosphere(1) have designated point maintainers. Pull requests to these projects should be approved by the point maintainer when possible:

Ancillary projects have a wider set of individuals with write access, these are typically members of the Atmosphere(0) team at CyVerse.

How Atmosphere is Tested

The stack is tested at various levels; test coverage and the testing process is a work in progress.

Django tests in Atmosphere(2)

Unit tests written by developers can be found throughout the codebase. These tests are not currently running as part of regular build/deploy workflow, but we could!

Travis CI running style & bundle/compile tests for Troposphere

QA Team tests using Robot Framework and JMeter

Note that the following information describes processes performed by the QA Team at CyVerse who primarily support Atmosphere(0), but their effort certainly also benefits Atmosphere(1). This team is also responsible for testing other CyVerse products (e.g. Discovery Environment). Some resources described in this section are currently only accessiblt to members of CyVerse staff.

Tests are built based on QA team using and reverse engineering Atmosphere(1) on atmobeta.cyverse.org, and the history of internal JIRA issues. QA team does not currently receive product specifications or release notes.

Individual tests are tagged in a few dimensions:

  • Type of test
    • Smoke tests, which confirm very basic communication/functionality/existence of API and UI objects
    • Functional tests, which confirm the actual functioning ("golden path") of API endpoints and UI objects
    • Regression tests, which confirm that resolved issues do not recur and pushes boundaries
  • Layer of stack under test
    • Atmosphere(2) API (HTTP calls using curl)
    • Troposphere UI (browser driven with Selenium)

atmobeta.cyverse.org is tested nightly, and test results can be found on https://shimerdas.iplantcollaborative.org:8443. (You must be a member of CyVerse staff and on an internal network to access shimerdas Jenkins server.) Only atmobeta is targeted during regression testing.

atmo-dev.cyverse.org is tested as part of each continuous deployment. Jenkins runs tests against atmo-dev in two jobs (these links are only accessible to CyVerse staff):

Test coverage is greater for the Atmosphere(2) API than for the Troposphere UI. QA team's tests do not currently confirm that instances launch, nor do they execute the various instance access workflows (e.g. Web Shell and Web Desktop), but it is possible for this coverage to be added.

If a test fails repeatedly, QA team files a JIRA ticket, tags the test with the JIRA number, and disables that test until the issue is resolved.

More information on the QA team's work can be found on qa-4.cyverse.org, including the automated test suites and how to run test suites locally (1, 2). (Only accessible to CyVerse staff.) Note that much of the information is for other CyVerse projects, and some test framework dependencies are unnecessary if you are only testing Atmosphere.

Operation Sanity behavioral testing

Operation Sanity is a set of test suites written using behave, which drive a browser using Selenium. Operation Sanity exercises common Atmosphere workflows as a user: launches several instances against multiple cloud providers, ensures that those instances launch, creates and attaches volumes, and so forth. It is intended to run these tests in parallel so that long operations (e.g. waiting for an instance to launch) do not block execution.

Operation Sanity is currently in a "proof of concept" state, and is currently not run automatically. There is some intended functionality (e.g. testing launch of Web Shell and Web Desktop) which needs to be built.

Releases and Development Cycles

You can see a list of releases as branches in each GitHub repository, e.g. Atmosphere(2).

Release Naming & "Code Names"

Starting in August 2017, Atmosphere releases named by a number preceded by a "v", v27. This marked the 27th major released of the product. Each major release will be incremented by one.

Previously, the name was two words, a hyphen was be added between them. Hyphenated bird names used to be the golden ticket (Abyssinian-nightjar,california-condor) but we later allow for alliterative adjective/verb and bird name combinations (ex: jamming-junglefowl, mystifying-merlin, nautical-nighthawk). The final release using this naming approach was zesty-zapdos.

Approach to Tagging Releases

In order to identify which release a repository is associated with, we need to "tag", or annotate, the association. Currently, we name branches by release for Atmosphere & Troposphere. However, there are dependencies in the instance deployment automation managed in Atmosphere-Ansible repository. This repo is used by "subspace" via Atmosphere API - yet, we are not explicitly denoting the Atmosphere-Ansible tested, verified, and deployed with an Atmosphere release.

I suggest that we use "annotated-tags" over lightweight tags; this allows for a "tag name" and a message.

Given that we use an integer number preceded by 'v' for release names. So releases would be tagged v##-1. Subsequent patch release would increase by one: v30-1, v30-2, v30-3, ...

Below are a few examples: - v27-1 - v27-2 - v28-1 - v28-2 - v28-3 - v29-1 - v30-1

Applying an annotated tag to a repository would allow a tag-name and a message. We'd then push to the origin without specifying a branch:


GIT_TAG="v28-1"
git tag -a $GIT_TAG -m "v28 (..release-codename..) release 1." && git push origin --tags</pre>

Note on "Sequence"

The tag-name should be have preceding v, "v for version", follow by a "two-digit" number that is an increasing integer representing the number of major releases of Atmosphere.

What Should Be Tagged?

The repositories that should be tagged for a release are as follows:

  • Atmosphere (:release-name branch) - repo
  • Troposphere (:release-name branch) - repo
  • Atmosphere-Ansible (master) - repo
  • Clank (master) - repo
  • nginx_novnc_auth (master) - repo

We should consider tagging this fork - https://github.com/edwins/gateone

Who Can Tag?

You have to be an admin of a repository to be able to tag releases. Ask an admin to create the tag if you don't have access.

Release Structure

The structure of releases is inspired by Chrome/Chromium. We aim to deliver new code to production every 5 weeks. Those 5 weeks are split into 3 sprints (2 sprints of 2-weeks and a single 1-week sprint).

First 2-week Sprint

  • new feature development
  • upgrading dependencies
  • testing/verification

Second 2-week Sprint

  • Priority bug fixes
  • feature development continued
  • testing/verification

Third 1-week Sprint

  • Any committed works left to finish
  • Priority/Critical tickets
  • testing/verification

Code Branching Strategy

(Note that the following section contains links to environments that are only accessible to members of CyVerse staff.)

The master branch collects new feature development and community contributions. http://atmo-dev.cyverse.org generally tracks master. Other feature branches are used as needed.

The 'beta' / 'next release' branch collects stability improvements and bug fixes; it does not typically receive new features. http://atmobeta.cyverse.org generally tracks the next release.

Think of each five-week cycle as an effort to 1. develop new features on the master branch, and 2. stabilize the beta/release branch for deployment to production.

Bug fixes and other changes are regularly "trickled down" from the beta/release branch to the master branch, and when necessary, from production systems to beta/release.

Following each release, any changes in the release branch are merged back into master. Then, master is branched into the 'next release' and the cycle repeats.