⚠️This repository is no longer updated

This project was developed at LiveRamp, but is no longer the canonical home
of future progress on this project. To download the latest version, report
an issue or submit a pull request, please visit joshk0/terraorg.

Any perspectives or direction on the canonical repository are endorsed
solely by its author and not by LiveRamp.

terraorg

This tool helps define organizational structure using flat JSON files as a
source of truth for who is a member of an organization. Traditionally, there
are multiple sources of truth that need to be separately maintained. These JSON
files are processed into Terraform files which are meant to create nested
groups representing the organization that are usable in Okta and G Suite.

Additionally, the tool facilitates using this source of truth to generate
Markdown documentation about the org as well.

Based on the org that this tool was originally designed for, orgs are expected
to have three levels:

• squads: the base unit of team-dom, containing people, who may be in
  different geographical regions.
• platoons: a unit which contains squads and exceptional people who are
  members of the platoon, but not part of any squad
• org: The whole organization, including its manager, any exceptional squads
  not organized into a platoon, and any exceptional people not part of any
  squad at all but still part of the org.

The tool generates groups for each granular unit of organization in Okta and G
Suite in Terraform. With patching, it could be possible for more organizational
systems to be supported.

How it works

Firstly, take your entire existing organization and define it using the
constructs of squads, platoons and organization. Groups will be generated;
use these groups to assign access to resources rather than individually
assigning access.

Whenever a person joins your organization, it should be the responsibility of
managers in the organization, or their delegates, to update the organizational
JSON files. If done correctly, updating the file, re-running terraorg to
generate source code, and applying the resulting source code would instantly
grant the person access to required services. Similarly, if a person leaves,
remove that person from the file and run the tool again.

Model definitions

See examples/ directory for examples of squads.json, platoons.json and
org.json.

Running the tool

Environment variables

The tool expects the following environment variables to be defined and fails if
they are missing:

• OKTA_API_TOKEN: An API token with read/write admin access to your Okta
  organization.
• OKTA_ORG_NAME: Name of the Okta organization.
• OKTA_BASE_URL: either okta.com or oktapreview.com depending on your
  Okta configuration.
• GSUITE_DOMAIN: The G Suite domain suffix e.g. yourcompany.com which
  is used by Google Groups.

The following environment variables are optional; if not specified, ensure
that your runtime setup matches the defaults.

• TERRAORG_SQUADS: defaulting to squads.json, location of the squads
  definition.
• TERRAORG_PLATOONS: defaulting to platoons.json, location of the platoons
  definition.
• TERRAORG_ROOT: defaulting to org.json, location of the root
  organizational unit.
• TERRAORG_OKTA_CACHE: defaulting to okta_cache.json, location of the Okta
  name, email and user id lookup cache. Delete this file to force a refresh.
• SLACK_DOMAIN: defaulting to yourdomain.slack.com, prefix of your Slack
  domain. This is only required for doc generation and not for Terraform.

Subcommands

When running terraorg, pass a second argument containing a subcommand.
Valid subcommands:

• fmt: Idiomatic formatting for all of your org files which will be
  written back to the JSON files. Similar behavior to terraform fmt.
  auto.XXXX.tf.
• generate-platoons-md: Generate Markdown documentation for Squads.
• generate-squads-md: Generate Markdown documentation for Squads.
• generate-tf: Generate Terraform files. Output files will be of the form
• validate: Ensure the input JSON files represent a valid, self-consistent
  organization.

Combining with terraform

See examples/ directory for how to set up your Terraform workspace for plans
and applies of the files generated by this tool. At a minimum, you will need to
furnish articulate/terraform-provider-okta and
DeviaVir/terraform-provider-gsuite, and enable those as providers.

Please consult the respective Terraform modules’ home pages for more
information on how to configure the providers.

Suggested process

At LiveRamp, a pull request based workflow leveraging Atlantis is used to
interact with terraorg. The repository containing LiveRamp’s engineering
organizational structure is locked down and requires approval from
organizational leadership for any change.

Once approved, Atlantis leverages its API access to Okta and G Suite in order
to effect the group changes.

Similar process can be defined using CI tools such as Jenkins and Circle CI.
Implementation of such process is left as an exercise to the reader.

Future

• terraorg could generate and push GitHub Teams automatically that line up
  with existing squad structure.
• Terraform and Markdown generation could be factored out to ERB.