Package: gen3cirrus
cirrusCloud Management Library wrapping Cloud APIstl;drfrom cirrus import GoogleCloudManager

# Uses file-like syntax for opening a connection to Google's API
with GoogleCloudManager() as g_mngr:
    project_buckets = g_mngr.get_buckets()

    new_group = g_mngr.create_group("group-0")
    new_service_account = g_mngr.create_service_account("service-account-0")

    g_mngr.add_member_to_group(new_service_account["email"], new_group["email"])tl;dr caveat:You have to have everything setup and configured correctly before
using the library like above.So... you should at least read how to set up your environment.Setting up Environment forcirruscirrus's wispy clouds must dwell in the great blue expanse with other Clouds.
Thus, you'll need to configurecirruswith necessary information about those Clouds
before being able to bask in its beauty.Youshouldonly have to do this once so don't freak out.By default, all the configurations needed bycirrusare assumed to be environmental
variables. You can also provide the configuration programatically in Python (instructions are later in the README).Note:This guide should cover necessary configuration,
but in the effort of not having to maintain everything in two places,
make sure to check thecirrus/config.pyfor other configuration options.Google Cloud Platform (GCP) ConfigurationTo use this library for GCP, it must be configured with credentials for a
Google Cloud Platform project along with a few other things.Project Configurationcirrussupports the management of GCP projects. We need the name of a single default Google project to manage though.Managing another project is possible by passing theproject_idwhen initializing aGoogleCloudManager.Make sure what you provide is the actual ProjectIDand not just the ProjectName. Google requires these are globally unique, so if you usedtest-projectduring creation, Google may have appended something to the end to make the name unique.# The unique ID for the Google Cloud Project to manage by default
GOOGLE_PROJECT_ID="test-project-0"Enable APIs and services on your project (you can selectively enable these depending on which functions of cirrus you plan on using):Google Identity and Access Management (IAM) APITo manage IAM policiesAdmin SDKFor group/user managementCloud Resource Manager APIFor reading Project metadataThe Google+ API may have to be enabled for some features to work as well.CredentialsYou'll need a service account with what permissions you want to allowcirrusto have. What these are depends on what functionality ofcirrusyou plan on using.For service account management you will probably need the following pre-defined Google roles:Service Account Admin-to manage service accountsService Account Token Creator-to manage service account keysService Account Key Admin-to delete service account keysViewer-to see project informationStorage Admin-to manage Google Storage bucketsSecurity Reviewer-to view IAM policiesRole Administrator-for creating a custom roles in a projectused only for providing an SA a custom role for billing permission as of nowProject IAM Admin-to update the project's policyused only for providing an SA a custom role for billing permission as of nowNOTE: It's possible you may need more or less roles/permissions (since Google may change these roles in the future). Just pay attention to any unauthorized errors you get when usingcirrusand see what permission Google is expecting.Now you need to create a key for that service account and download the keyfile.Now, setGOOGLE_APPLICATION_CREDENTIALSto the path to that keyfile.# Path to credentials for accessing the Google Cloud Project
GOOGLE_APPLICATION_CREDENTIALS="/path/to/keyfile/service-account-0.json"In addition to credentials,cirrusneeds to know the email address for
those credentials. You should be able to find the service account's email
in the Cloud Console.# Admin email for Google Cloud Project (should be a service account)
GOOGLE_ADMIN_EMAIL="admin@test-project-0.iam.gserviceaccount.com"Group ManagementIn order to manage groups,cirrusassumes you have aCloud Identity(or GSuite) domain. The methodcirrususes to manage groups is called
"domain-wide delegation" for a service account. You will need to follow
a few guides on settings that up, as it requires you to enable access to the
Cloud Identity/GSuite API.Follow directionshereto deletgate domain-wide authority for your service account that you're using
forGOOGLE_APPLICATION_CREDENTIALS.For the API scopes, authorize these:https://www.googleapis.com/auth/admin.directory.group,
https://www.googleapis.com/auth/admin.directory.group.readonly,
https://www.googleapis.com/auth/admin.directory.group.member,
https://www.googleapis.com/auth/admin.directory.group.member.readonly,
https://www.googleapis.com/auth/admin.directory.user.securityIMPORTANT NOTE:When providing the above scopes in Cloud Identity, make sure theClient Nameis the Oauth Client ID for the service account andnotthe service account's email. You can find the Client ID in the "APIs & Services -> Credentials" section of the Google Project in GCP. When you delegate domain-wide authority for a service account a new Client ID should automatically be created.Youmay need to wait(up to 48 hours) before access is granted.Once that's all done, you need to givecirrusinformation about the domain
and an admin user we can delegate to. The admin email you use needs
permissions to manage groups within your domain.# Domain for group management
GOOGLE_IDENTITY_DOMAIN="mydomain.com"

# Admin email for admin domain-wide service account to act for
GOOGLE_CLOUD_IDENTITY_ADMIN_EMAIL="admin@mydomain.com"Last but not least, you'll need to set up an API key for your GCP project and
provide it tocirrusto include in the Google API calls.# API key to use during API calls
GOOGLE_API_KEY="abcdefghijklmnopqrstuvwxyz"Setting Configuration Programaticallycirrus, by default, reads in necessary configurations from environmental variables. You can, however, provide all these config vars programatically by calling theupdatefunction on the config object incirrusand passing in a dictionary.For example:from cirrus.config import config as cirrus_config

settings = {
    "GOOGLE_PROJECT_ID": "some-project-id-123456789",
    "GOOGLE_APPLICATION_CREDENTIALS": "full/path/to/creds",
    "GOOGLE_ADMIN_EMAIL": "some-project-id-123456789",
    "GOOGLE_IDENTITY_DOMAIN": "mydomain.com",
    "GOOGLE_CLOUD_IDENTITY_ADMIN_EMAIL": "admin@mydomain.com",
    "GOOGLE_API_KEY": "abcdefghijklmnopqrstuvwxyz"
}

cirrus_config.update(**settings)Google Specific Implementation DetailsDifferent Methods For Communication with Google's API(s)Method 1) General Python library for communicating with all APIsUse the Google API Python Clienthttps://github.com/google/google-api-python-clientAllows for building a general service to communicate with any APIAccess REST APIs through Python function callsNOTE: For Cloud Platform API's, Google recommends using Method 2Method 2) Specialized Python library tailored to an APIUse the Google Cloud Client Library for Python for communicating with Cloud Platform serviceshttps://github.com/GoogleCloudPlatform/google-cloud-pythonRecommended for use over Method 1 above but only stably supports some APIsMethod 3) Custom service to communicate directly using REST APIMore flexibilityCan use same service for multiple different APIsRelies less* on Google's libraries (double-edged sword)Still uses Google libraries for authBuilding the Documentationpipenv install --devpipenv run python docs/create_docs.pyHTML is generated in thedocs/buildfolderRelease New VersionsCreate a new release fromhttps://github.com/uc-cdis/cirrus/releases/new, tag version
must be a proper Python package version, and must be ascending. Then Travis will
automatically build a new package and upload to PyPI, and update the GitHub release with
proper release notes. So you just need to provide a proper release title, leaving the
description empty and the automation tool will fill it for you.