terraorg 0.0.7

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8ab3d94ce6dcc408a54773d2922f6939cb3ecb2c1f712c15e6bf38d5b4991262
+  data.tar.gz: 697c67ca943cc95ea5aad8a569968f204d0c6ed54e5747b4e99a55090c8faa6c
+SHA512:
+  metadata.gz: eea771dfd0e78861b6bc4d40bd6a55a978ee05a7a2739948bfa1ce7890dd26bd59a534395973b28fa9caff76c06d143cf482bb9d22278f89fb4ba9b92cb06172
+  data.tar.gz: a2199d855c507de8ed37a22a62a20d65a36796637ff7ed55003fd205380655ffb2eebcbbc51720eec747ea46252705a00fa9a528581cc4f5756dab5d27bb1f2c

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright 2020- Joshua Kwan
+Copyright 2020 LiveRamp Holdings, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,124 @@
+[![Build Status](https://travis-ci.com/joshk0/terraorg.svg?token=KqPPGKhNmsFv3uhyxvvf&branch=master)](https://travis-ci.com/joshk0/terraorg)
+
+# 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.
+
+[articulate/terraform-provider-okta]: https://github.com/articulate/terraform-provider-okta
+[DeviaVir/terraform-provider-gsuite]: https://github.com/DeviaVir/terraform-provider-gsuite
+
+## 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.
+
+[LiveRamp]: https://github.com/LiveRamp/
+[Atlantis]: https://www.runatlantis.io/
+
+## 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.

data/bin/terraorg

@@ -0,0 +1,100 @@
+#!/usr/bin/env ruby
+
+require 'json'
+require 'neatjson'
+require 'oktakit'
+
+require 'terraorg/model/org'
+require 'terraorg/model/people'
+require 'terraorg/model/platoons'
+require 'terraorg/model/squads'
+
+ACTIONS = [
+  'fmt',
+  'generate-platoons-md',
+  'generate-squads-md',
+  'generate-tf',
+  'validate'
+].freeze
+
+SQUADS_FILE = ENV.fetch('TERRAORG_SQUADS', 'squads.json')
+PLATOONS_FILE = ENV.fetch('TERRAORG_PLATOONS', 'platoons.json')
+ORG_FILE = ENV.fetch('TERRAORG_ROOT', 'org.json')
+CACHE_FILE = ENV.fetch('TERRAORG_OKTA_CACHE', 'okta_cache.json')
+GSUITE_DOMAIN = ENV.fetch('GSUITE_DOMAIN')
+SLACK_DOMAIN = ENV.fetch('SLACK_DOMAIN', 'yourcompany.slack.com')
+OKTA_ORG_NAME = ENV.fetch('OKTA_ORG_NAME')
+OKTA_API_TOKEN = ENV.fetch('OKTA_API_TOKEN')
+OKTA_BASE_URL = ENV.fetch('OKTA_BASE_URL', 'okta.com')
+
+action = ARGV[0]
+raise "Invalid action: '#{action}' (valid: #{ACTIONS})" unless ACTIONS.member?(action)
+
+### Actions that can run without Okta
+case action
+when 'fmt'
+  # This People object is created with neither an okta cache nor a okta client.
+  # It accepts any user for the purposes of format validation.
+  people = People.new
+  squads_data = File.read(SQUADS_FILE)
+  squads = Squads.new(JSON.parse(squads_data), people, GSUITE_DOMAIN, SLACK_DOMAIN)
+  platoons_data = File.read(PLATOONS_FILE)
+  platoons = Platoons.new(JSON.parse(platoons_data), squads, people, GSUITE_DOMAIN)
+  org_data = File.read(ORG_FILE)
+  org = Org.new(JSON.parse(org_data), platoons, squads, people, GSUITE_DOMAIN)
+
+  options = {wrap: true, sort: true, after_colon: 1, after_comma: 1}
+  new_squads_data = JSON.neat_generate(squads.to_h, **options) + "\n"
+  new_platoons_data = JSON.neat_generate(platoons.to_h, **options) + "\n"
+  new_org_data = JSON.neat_generate(org.to_h, **options) + "\n"
+
+  if new_squads_data != squads_data
+    puts SQUADS_FILE
+    File.write(SQUADS_FILE, new_squads_data)
+  end
+
+  if new_platoons_data != platoons_data
+    puts PLATOONS_FILE
+    File.write(PLATOONS_FILE, new_platoons_data)
+  end
+
+  if new_org_data != org_data
+    puts ORG_FILE
+    File.write(ORG_FILE, new_org_data)
+  end
+
+  exit
+end
+
+### Actions that require Okta credentials
+if OKTA_BASE_URL == 'oktapreview.com'
+  okta = Oktakit.new(token: OKTA_API_TOKEN, api_endpoint: "https://#{OKTA_ORG_NAME}.#{OKTA_BASE_URL}/api/v1")
+else
+  okta = Oktakit.new(token: OKTA_API_TOKEN, organization: OKTA_ORG_NAME)
+end
+
+people = People.new(okta: okta, cache_file: CACHE_FILE)
+squads_data = File.read(SQUADS_FILE)
+squads = Squads.new(JSON.parse(squads_data), people, GSUITE_DOMAIN, SLACK_DOMAIN)
+platoons_data = File.read(PLATOONS_FILE)
+platoons = Platoons.new(JSON.parse(platoons_data), squads, people, GSUITE_DOMAIN)
+org_data = File.read(ORG_FILE)
+org = Org.new(JSON.parse(org_data), platoons, squads, people, GSUITE_DOMAIN)
+
+org.validate!
+
+case action
+when 'generate-squads-md'
+  # Generate CSV file mirroring the 'Engineering Squads' Squads sheet.
+  puts org.get_squads_md
+when 'generate-platoons-md'
+  # Generate CSV file mirroring the 'Engineering Squads' Platoons sheet.
+  puts org.get_platoons_md
+when 'generate-tf'
+  # Generate Terraform code to apply to Okta.
+  org.generate_tf
+when 'validate'
+  # Validation is a prerequisite, so just output success. It would have
+  # failed earlier otherwise
+  puts 'Organization is valid!'
+end

data/lib/terraorg/model/org.rb

@@ -0,0 +1,231 @@
+require 'terraorg/model/util'
+
+class Org
+  MAX_SQUADS_PER_PERSON = 2
+  SCHEMA_VERSION = 'v1'.freeze
+
+  def initialize(parsed_data, platoons, squads, people, gsuite_domain)
+    @people = people
+    @id = parsed_data.fetch('id')
+    @name = parsed_data.fetch('name')
+    @metadata = parsed_data.fetch('metadata', {})
+    @manager = @people.get_or_create!(parsed_data.fetch('manager'))
+    @manager_location = parsed_data.fetch('manager_location')
+    # @member_exception_people is a Hash of Squad::Teams, like the teams attribute in a Squad.
+    @member_exception_people = Hash[parsed_data.fetch('exception_people').map { |p|
+      [p.fetch('location'), Squad::Team.new(p, @people)]
+    }]
+    @member_exception_squad_names = []
+    @member_exception_squads = parsed_data.fetch('exception_squads').map do |s|
+      @member_exception_squad_names.push(s)
+      squads.lookup!(s)
+    end
+    @member_platoon_names = []
+    @member_platoons = parsed_data.fetch('platoons').map do |p|
+      @member_platoon_names.push(p)
+      platoons.lookup!(p)
+    end
+
+    # used to generate a group
+    @gsuite_domain = gsuite_domain
+
+    # used for validate!
+    @platoons = platoons
+    @squads = squads
+  end
+
+  def validate!
+    # Do not allow the JSON files to contain any people who have left.
+    raise "Users have left the company: #{@people.inactive.map(&:id).join(', ')}" unless @people.inactive.empty?
+
+    # Do not allow the org to be totally empty.
+    raise 'Org has no platoons or exception squads' if @member_platoons.size + @member_exception_squads.size == 0
+
+    # Require all platoons to be part of the org.
+    platoon_diff = Set.new(@platoons.all_names) - Set.new(@member_platoon_names)
+    unless platoon_diff.empty?
+      raise "Platoons are not used in the org: #{platoon_diff.to_a.sort}"
+    end
+
+    # Require all squads to be used in the org.
+    squad_diff = Set.new(@squads.all_names) - Set.new(@platoons.all_squad_names) - Set.new(@member_exception_squad_names)
+    unless squad_diff.empty?
+      raise "Squad(s) are not used in the org: #{squad_diff.to_a.sort}"
+    end
+
+    all_squads = (@member_platoons.map(&:member_squads) + @member_exception_squads).flatten
+    seen_squads = {}
+
+    # Validate that a squad is not part of more than one platoon
+    all_squads.map(&:id).each do |id|
+      seen_squads[id] = seen_squads.fetch(id, 0) + 1
+    end
+    more_than_one_platoon = seen_squads.select do |squad, count|
+      count > 1
+    end
+    if !more_than_one_platoon.empty?
+      raise "Squads are part of more than one platoon: #{more_than_one_platoon}"
+    end
+
+    # Validate that a squad member belongs to at most two squads in the entire org
+    squad_count = {}
+    all_squads.map(&:teams).flatten.map(&:values).flatten.map(&:members).flatten.each do |member|
+      squad_count[member.id] = squad_count.fetch(member.id, 0) + 1
+    end
+    more_than_max_squads = squad_count.select do |member, count|
+      count > MAX_SQUADS_PER_PERSON
+    end
+    if !more_than_max_squads.empty?
+      # TODO(joshk): Enforce after consulting with Sean
+      $stderr.puts "WARNING: Members are part of more than #{MAX_SQUADS_PER_PERSON} squads: #{more_than_max_squads}"
+    end
+
+    # Validate that a squad member is not also an org exception
+    exceptions = Set.new(@member_exception_people.map { |_, t| t.members }.flatten.map(&:id))
+    exception_and_squad_member = squad_count.keys.select do |member|
+      exceptions.member? member
+    end
+    if !exception_and_squad_member.empty?
+      raise "Exception members are also squad members: #{exception_and_squad_member}"
+    end
+  end
+
+  def members
+    Set.new([@manager] + (@member_platoons + @member_exception_squads).map(&:members).flatten + @member_exception_people.map { |_, t| t.members }.flatten).to_a
+  end
+
+  def get_acl_groups(attr: :id)
+    # Return a LIST_NAME => [MEMBER1, MEMBER2...] hash of ACL groups
+    { unique_name => members.map(&attr).sort }.
+      merge(get_platoon_acl_groups(attr: attr)).
+      merge(get_exception_squad_acl_groups(attr: attr))
+  end
+
+  def get_platoon_acl_groups(attr: :id)
+    @member_platoons.map { |p| p.get_acl_groups(@id, attr: attr) }.reduce({}, :merge)
+  end
+
+  def get_exception_squad_acl_groups(attr: :id)
+    @member_exception_squads.map { |p| p.get_acl_groups(@id) }.map(&attr).reduce({}, :merge)
+  end
+
+  def unique_name
+    "#{@id}-all"
+  end
+
+  def get_platoons_md
+    # 90 degree rotated version of the Platoons page of the legacy Engineering Squads sheet
+    # Format:
+    # Platoon,Total,Members
+    # [ORG_HUMAN_NAME],[COUNT]
+    # [PLAT1_HUMAN_NAME],[PLAT1_COUNT],[PLAT1_MEMBER1],[PLAT1_MEMBER2],...
+    # [PLAT2_HUMAN_NAME],[PLAT2_COUNT],[PLAT2_MEMBER1],[PLAT2_MEMBER2],...
+    md_lines = [
+      '# Engineering Platoons List',
+      '',
+      '|Platoon|Manager|Total|Members|',
+      '|---|---|---|---|',
+      "|_#{@name} Total_|#{@manager.name}|#{members.size}|",
+    ]
+    md_lines += @member_platoons.map(&:get_platoons_psv_row)
+
+    raise "Users have left the company: #{@people.inactive.map(&:id).join(', ')}" unless @people.inactive.empty?
+    md_lines.join("\n")
+  end
+
+  def get_squads_md
+    # Format:
+    # platoon name, squad name, PM, email list, SME, slack, # people, squad manager, eng product owner, members
+    md_lines = [
+      '# Engineering Squads List',
+      '',
+      '|Platoon|Squad|PM|Mailing list|TS SME|Slack|# Engineers|Squad Manager|Eng Product Owner|Members|',
+      '|---|---|---|---|---|---|---|---|---|---|',
+    ]
+    md_lines += @member_platoons.map { |s| s.get_squads_psv_rows(@id) }
+    md_lines += @member_exception_squads.map { |s| s.to_md('_No Platoon_', @id) }
+    md_lines.push "|_No Platoon_|_No Squad_|||||#{@member_exception_people.size}|||#{@member_exception_people.values.map(&:to_md).join(' / ')}|"
+
+    raise "Users have left the company: #{@people.inactive.map(&:id).join(', ')}" unless @people.inactive.empty?
+    md_lines.join("\n")
+  end
+
+  def generate_tf
+    tf = @member_platoons.map { |p| p.generate_tf(@id) }.join("\n")
+    File.write('auto.platoons.tf', tf)
+
+    tf = @member_exception_squads.map { |s| s.generate_tf(@id) }.join("\n")
+    File.write('auto.exception_squads.tf', tf)
+
+    # Roll all platoons and exception squads into the org.
+    roll_up_to_org = \
+      @member_exception_squads.map { |s| s.unique_name(@id, nil) } + \
+      @member_platoons.map { |p| p.unique_name(@id) }
+
+    # Generate the org, which contains:
+    # - exception people (added manually to group)
+    # - the org manager (added manually to group)
+    # - all the platoons (via rule)
+    # - all exception squads (via rule)
+    org_condition = roll_up_to_org.map {
+      |n| "\\\"${okta_group.#{n}.id}\\\""
+    }.join(',')
+
+    description = "#{@name} organization worldwide members (terraorg)"
+    tf = <<-EOF
+# Okta for Organization: #{@name}
+resource "okta_group" "#{unique_name}" {
+  name = "#{unique_name}"
+  description = "#{description}"
+  users = #{Util.persons_tf(members)}
+}
+
+#{Util.gsuite_group_tf(unique_name, @gsuite_domain, members, description)}
+EOF
+
+    # Generate a special group for all org members grouped by country
+    all_squads = (@member_platoons.map(&:member_squads) + @member_exception_squads).flatten
+    all_locations = {}
+    (all_squads.map(&:teams).flatten + [@member_exception_people]).each do |team|
+      team.each do |location, subteam|
+        all_locations[location] = all_locations.fetch(location, Set.new).merge(subteam.members)
+      end
+    end
+
+    # Manually add the manager to a specific location
+    all_locations[@manager_location] = all_locations.fetch(@manager_location, Set.new).add(@manager)
+
+    all_locations.each do |l, m|
+      name = "#{unique_name}-#{l.downcase}"
+      tf += <<-EOF
+resource "okta_group" "#{name}" {
+  name = "#{name}"
+  description = "#{@name} organization members based in #{l} (terraorg)"
+  users = #{Util.persons_tf(m)}
+}
+EOF
+    end
+
+    File.write('auto.org.tf', tf)
+  end
+
+  # Output a canonical (sorted, formatted) version of this organization.
+  # - Sort the platoon names lexically
+  # - Sort the exception squad ids lexically
+  # - Sort the exception people ids lexically
+  def to_h
+    obj = { 'version' => SCHEMA_VERSION, 'id' => @id, 'name' => @name, 'manager_location' => @manager_location, 'manager' => @manager.id }
+    obj['platoons'] = @platoons.all.map(&:id).sort
+    if @metadata
+      obj['metadata'] = @metadata
+    end
+    if @member_exception_people
+      obj['exception_people'] = @member_exception_people.values.sort_by(&:location).map(&:to_h)
+    end
+    if @member_exception_squads
+      obj['exception_squads'] = @member_exception_squads.map(&:id).sort
+    end
+
+    obj
+  end
+end

data/lib/terraorg/model/people.rb

@@ -0,0 +1,44 @@
+require 'terraorg/model/person'
+
+class People
+  attr_accessor :inactive
+
+  def initialize(okta: nil, cache_file: nil)
+    @okta = okta
+    @people = {}
+    @inactive = []
+    @cache_file = cache_file
+
+    load_cache! if @cache_file
+  end
+
+  def get_or_create!(id)
+    p = @people[id]
+    return p if p
+
+    p = Person.new(id, okta: @okta)
+    if p.active?
+      @people[id] = p
+    else
+      @people.delete(id)
+      @inactive.push p
+    end
+    save_cache! if @cache_file
+    return p
+  end
+
+  def load_cache!
+    return unless File.exist?(@cache_file)
+
+    JSON.parse(File.read(@cache_file)).each do |id, cache|
+      @people[id] = Person.new(id, cached: cache)
+    end
+  end
+
+  def save_cache!
+    # Atomic write cache file
+    cf_new = "#{@cache_file}.new"
+    File.write(cf_new, @people.to_json)
+    File.rename(cf_new, @cache_file)
+  end
+end

data/lib/terraorg/model/person.rb

@@ -0,0 +1,63 @@
+require 'faraday'
+
+class Person
+  ACTIVE_USER_STATUSES = ['ACTIVE', 'PROVISIONED'].freeze
+
+  attr_accessor :id, :name, :okta_id, :email, :status
+
+  def initialize(uid, okta: nil, cached: nil)
+    @id = uid
+
+    if cached
+      @name = cached.fetch('name')
+      @okta_id = cached.fetch('okta_id')
+      @email = cached.fetch('email')
+      @status = cached.fetch('status')
+
+      return
+    elsif !okta
+      # We could just be running in fmt mode, so lie about everything
+      @name = "real name of #{@id}"
+      @okta_id = "fake okta id for #{@id}"
+      @email = "#{@id}@my.domain"
+      @status = 'PROVISIONED'
+
+      return
+    end
+
+    # Retrieve from okta
+    tries = 1
+    total_tries = 5
+
+    begin
+      o = okta.get_user(uid)
+    rescue Faraday::ConnectionFailed => e
+      if tries <= total_tries
+        puts "looking up user #{uid}: #{e} (try #{tries}/#{total_tries})"
+        tries += 1
+        retry
+      end
+      raise
+    end
+
+    if tries > 1
+      puts "looking up user #{uid}: success!"
+    end
+
+    # NOTE: allows users in states other than ACTIVE
+    # if you want to check that, do it outside of here
+    obj = o[0].to_hash
+    @name = obj.fetch(:profile).fetch(:displayName)
+    @okta_id = obj.fetch(:id)
+    @email = obj.fetch(:profile).fetch(:email)
+    @status = obj.fetch(:status)
+  end
+
+  def active?
+    ACTIVE_USER_STATUSES.member?(@status)
+  end
+
+  def to_json(options = nil)
+    {'id' => @id, 'name' => @name, 'okta_id' => @okta_id, 'email' => @email, 'status' => @status}.to_json
+  end
+end

data/lib/terraorg/model/platoon.rb

@@ -0,0 +1,98 @@
+require 'terraorg/model/util'
+
+class Platoon
+  attr_accessor :id, :name, :member_exceptions, :member_squads
+
+  def initialize(parsed_data, squads, people, gsuite_domain)
+    @id = parsed_data.fetch('id')
+    @metadata = parsed_data.fetch('metadata', {})
+    @name = parsed_data.fetch('name')
+    @manager = people.get_or_create!(parsed_data.fetch('manager'))
+    @member_exceptions = parsed_data.fetch('exceptions', []).map do |n|
+      people.get_or_create!(n)
+    end
+    @member_squad_names = []
+    @member_squads = parsed_data.fetch('squads').map do |s|
+      @member_squad_names.push(s)
+      squads.lookup!(s)
+    end
+    @gsuite_domain = gsuite_domain
+  end
+
+  def validate!
+    raise 'Platoon has no squads' if @member_squads.size == 0
+  end
+
+  def squad_names
+    @member_squad_names
+  end
+
+  def members
+    Set.new([@manager] + @member_squads.map(&:members).flatten + @member_exceptions).to_a
+  end
+
+  def unique_name(org_id)
+    "#{org_id}-platoon-#{@id}"
+  end
+
+  def get_acl_groups(org_id, platoon: true)
+    if platoon
+      rv = { unique_name(org_id) => {'name' => "#{@name} platoon members worldwide", 'members' => members} }
+    else
+      rv = {}
+    end
+
+    @member_squads.map { |s| s.get_acl_groups(org_id) }.reduce(rv, :merge)
+  end
+
+  def get_platoons_psv_row
+    "|#{@name}|#{@manager.name}|#{members.size}|#{members.map(&:name).sort.join(', ')}|"
+  end
+
+  def get_squads_psv_rows(org_id)
+    @member_squads.map { |s| s.to_md(@name, org_id) }
+  end
+
+  def generate_tf(org_id)
+    tf_id = unique_name(org_id)
+
+    # tf formatted, comma separated references to the group ids for the
+    # squads in this platoon
+    squads_condition = get_acl_groups(org_id, platoon: false).map {
+      |n, _| "\\\"${okta_group.#{n}.id}\\\""
+    }.join(',')
+
+    # tf containing the platoon declaration
+    description = "#{@name} platoon members (terraorg)"
+    rv = <<-EOF
+# Platoon: #{@name}
+# Squads: #{squad_names.join(', ')}
+
+resource "okta_group" "#{tf_id}" {
+  name = "#{tf_id}"
+  description = "#{description}"
+  users = #{Util.persons_tf(members)}
+}
+
+#{Util.gsuite_group_tf(tf_id, @gsuite_domain, members, description)}
+EOF
+
+    # tf containing squads and their members
+    rv += @member_squads.map { |s| s.generate_tf(org_id) }.join("\n")
+  end
+
+  # Output a canonical (sorted, formatted) version of this object.
+  # - Sort the squad ids lexically
+  # - Sort the exceptions lexically
+  def to_h
+    obj = { 'id' => @id, 'name' => @name, 'manager' => @manager.id, 'squads' => @member_squads.map(&:id) }
+    unless @member_exceptions.empty?
+      obj['exceptions'] = @member_exceptions.map(&:id)
+    end
+    unless @metadata.empty?
+      obj['metadata'] = @metadata
+    end
+
+    obj
+  end
+end

data/lib/terraorg/model/platoons.rb

@@ -0,0 +1,43 @@
+require 'terraorg/model/platoon'
+
+class Platoons
+  SCHEMA_VERSION = 'v1'.freeze
+
+  def initialize(parsed_data, squads, people, gsuite_domain)
+    version = parsed_data.fetch('version')
+    raise "Unsupported schema version: #{version}" if version != SCHEMA_VERSION
+
+    @platoons = {}
+    parsed_data.fetch('platoons').each do |platoon_raw|
+      p = Platoon.new(platoon_raw, squads, people, gsuite_domain)
+      @platoons[p.id] = p
+    end
+  end
+
+  def lookup!(name)
+    @platoons.fetch(name)
+  end
+
+  def validate!
+  end
+
+  def all
+    @platoons.values
+  end
+
+  def all_squad_names
+    @platoons.values.map(&:squad_names).flatten
+  end
+
+  def all_names
+    @platoons.keys
+  end
+
+  def members
+    @platoons.map(&:members).flatten
+  end
+
+  def to_h
+    { 'version' => SCHEMA_VERSION , 'platoons' => @platoons.values.sort_by(&:id).map(&:to_h) }
+  end
+end

data/lib/terraorg/model/squad.rb

@@ -0,0 +1,129 @@
+require 'terraorg/model/people'
+require 'terraorg/model/util'
+
+class Squad
+  attr_accessor :id, :name, :metadata, :teams
+
+  class Team
+    attr_accessor :location, :members
+
+    def initialize(parsed_data, people)
+      @location = parsed_data.fetch('location')
+      @members = parsed_data.fetch('members', []).map do |n|
+        people.get_or_create!(n)
+      end
+    end
+
+    # Output a canonical (sorted, formatted) version of this Team.
+    # - Sort the members in each team
+    def to_h
+      { 'location' => @location, 'members' => @members.map(&:id).sort }
+    end
+
+    def to_md
+      "**#{@location}**: #{@members.map(&:name).sort.join(', ')}"
+    end
+  end
+
+  def initialize(id, parsed_data, people, gsuite_domain, slack_domain)
+    @gsuite_domain = gsuite_domain
+    @slack_domain = slack_domain
+    @id = id
+    @metadata = parsed_data.fetch('metadata', {})
+    @name = parsed_data.fetch('name')
+    @people = people
+
+    teams_arr = parsed_data.fetch('team', []).map do |t|
+      Team.new(t, people)
+    end
+    @teams = Hash[teams_arr.map { |t| [t.location, t] }]
+  end
+
+  def members(location: nil)
+    @teams.select { |l, t|
+      location == nil || l == location
+    }.map { |l, t|
+      t.members
+    }.flatten
+  end
+
+  def get_acl_groups(org_id)
+    # each geographically located subteam
+    groups = Hash[@teams.map { |location, team|
+      [unique_name(org_id, location), {'name' => "#{@name} squad members based in #{location}", 'members' => team.members}]
+    }]
+
+    # combination of all subteams
+    groups[unique_name(org_id, nil)] = {'name' => "#{@name} squad worldwide members", 'members' => members}
+
+    groups
+  end
+
+  def unique_name(org_id, location)
+    if location
+      "#{org_id}-squad-#{@id}-#{location.downcase}"
+    else
+      "#{org_id}-squad-#{@id}"
+    end
+  end
+
+  def validate!
+    raise 'Squad has no members' if members.size == 0
+  end
+
+  def to_md(platoon_name, org_id)
+    pm = @metadata.fetch('pm', [])
+    pm = pm.map { |p| @people.get_or_create!(p).name }.join(', ')
+
+    sme = @metadata.fetch('sme', '')
+    if !sme.empty?
+      sme = @people.get_or_create!(sme).name
+    end
+
+    epo = @metadata.fetch('epo', '')
+    if !epo.empty?
+      epo = @people.get_or_create!(epo).name
+    end
+
+    manager = @metadata.fetch('manager', '')
+    if !manager.empty?
+      manager = @people.get_or_create!(manager).name
+    end
+
+    subteam_members = @teams.values.map(&:to_md).join(' / ')
+    email = "#{unique_name(org_id, nil)}@#{@gsuite_domain}"
+    slack = @metadata.fetch('slack', '')
+    if slack
+      slack = "[#{slack}](https://#{@slack_domain}/app_redirect?channel=#{slack.gsub(/^#/, '')})"
+    end
+    # platoon name, squad name, PM, email list, SME, slack, # people, squad manager, eng product owner, members
+    "|#{platoon_name}|#{@name}|#{pm}|[#{email}](#{email})|#{sme}|#{slack}|#{members.size}|#{manager}|#{epo}|#{subteam_members}|"
+  end
+
+  def generate_tf(org_id)
+    groups = get_acl_groups(org_id)
+
+    groups.map { |id, group|
+      description = "#{group.fetch('name')} (terraorg)"
+      <<-EOF
+resource "okta_group" "#{id}" {
+  name = "#{id}"
+  description = "#{description}"
+  users = #{Util.persons_tf(group.fetch('members'))}
+}
+
+#{Util.gsuite_group_tf(id, @gsuite_domain, group.fetch('members'), description)}
+EOF
+    }.join("\n\n")
+  end
+
+  def to_h
+    # Output a canonical (sorted, formatted) version of this Squad.
+    # - Subteams are sorted by location lexically
+    obj = { 'id' => @id, 'name' => @name }
+    obj['team'] = @teams.values.sort_by { |t| t.location }.map(&:to_h)
+    obj['metadata'] = @metadata if @metadata
+
+    obj
+  end
+end

data/lib/terraorg/model/squads.rb

@@ -0,0 +1,28 @@
+require 'terraorg/model/squad'
+
+class Squads
+  SCHEMA_VERSION = 'v1'.freeze
+
+  def initialize(parsed_data, people, gsuite_domain, slack_domain)
+    version = parsed_data.fetch('version')
+    raise "Unsupported squads schema version: #{version}" if version != SCHEMA_VERSION
+
+    @squads = {}
+    parsed_data.fetch('squads').each do |squad|
+      id = squad.fetch('id')
+      @squads[id] = Squad.new(id, squad, people, gsuite_domain, slack_domain)
+    end
+  end
+
+  def all_names
+    @squads.keys
+  end
+
+  def lookup!(name)
+    @squads.fetch(name)
+  end
+
+  def to_h
+    { 'version' => SCHEMA_VERSION, 'squads' => @squads.values.sort_by(&:id).map(&:to_h) }
+  end
+end

data/lib/terraorg/model/util.rb

@@ -0,0 +1,49 @@
+class Util
+  # Take a list of Persons and turn it into a newline delimited, comma
+  # separated array definition suitable for inclusion in terraform. Each line
+  # contains an okta id and a comment indicating the person's name.
+  def self.persons_tf(persons)
+    "[\n" + persons.map { |p| "    \"#{p.okta_id}\", # #{p.name}" }.join("\n") + "\n]\n"
+  end
+
+  # Take a list of Persons and generate a gsuite_group containing all of those
+  # members with expected organizational settings.
+  def self.gsuite_group_tf(name, domain, persons, description)
+    email = "#{name}@#{domain}"
+    tf = <<-TERRAFORM
+# G Suite group for #{email}
+resource "gsuite_group" "#{name}" {
+  email = "#{email}"
+  name  = "#{name}"
+  description = "#{description}"
+}
+
+resource "gsuite_group_settings" "#{name}" {
+  email = gsuite_group.#{name}.email
+  who_can_discover_group = "ALL_IN_DOMAIN_CAN_DISCOVER"
+  who_can_view_membership = "ALL_IN_DOMAIN_CAN_VIEW"
+  who_can_leave_group = "NONE_CAN_LEAVE"
+  who_can_join = "INVITED_CAN_JOIN"
+  who_can_post_message = "ALL_IN_DOMAIN_CAN_POST"
+}
+
+resource "gsuite_group_members" "#{name}" {
+  group_email = gsuite_group.#{name}.email
+TERRAFORM
+
+    # Add a member block for everyone
+    # downcase is used as internal G Suite representation is always lowercase
+    # this avoids unnecessary state churn
+    persons.each do |p|
+      tf += <<-TERRAFORM
+  member {
+    email = "#{p.email.downcase}"
+    role = "MEMBER"
+  }
+TERRAFORM
+    end
+
+    tf += "\n}"
+    tf
+  end
+end

data/lib/terraorg/version.rb

@@ -0,0 +1,3 @@
+module Terraorg
+  VERSION = '0.0.7'
+end

metadata

@@ -0,0 +1,97 @@
+--- !ruby/object:Gem::Specification
+name: terraorg
+version: !ruby/object:Gem::Version
+  version: 0.0.7
+platform: ruby
+authors:
+- Joshua Kwan
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2020-03-04 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1'
+- !ruby/object:Gem::Dependency
+  name: neatjson
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+- !ruby/object:Gem::Dependency
+  name: oktakit
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+description: Manage an organizational structure with Okta and G-Suite using Terraform
+email: joshk@triplehelix.org
+executables:
+- terraorg
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- bin/terraorg
+- lib/terraorg/model/org.rb
+- lib/terraorg/model/people.rb
+- lib/terraorg/model/person.rb
+- lib/terraorg/model/platoon.rb
+- lib/terraorg/model/platoons.rb
+- lib/terraorg/model/squad.rb
+- lib/terraorg/model/squads.rb
+- lib/terraorg/model/util.rb
+- lib/terraorg/version.rb
+homepage: https://github.com/LiveRamp/terraorg
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.3
+signing_key: 
+specification_version: 4
+summary: terraorg
+test_files: []