Skip to content

Commit

Permalink
Merge pull request #15 from kubermatic-labs/v2
Browse files Browse the repository at this point in the history 
Version 2
  • Loading branch information
@kubermatic-bot
kubermatic-bot authored Feb 4, 2021
2 parents b4ad5f5 + 1aa3342 commit 8482ac7
Show file tree
Hide file tree
Showing 34 changed files with 3,145 additions and 2,436 deletions.
9 changes: 1 addition & 8 deletions .gitignore
View file
Original file line number Diff line number Diff line change
@@ -1,15 +1,8 @@
# Binaries for programs and plugins
*.exe
*.exe~
*.dll
*.so
*.dylib

# Test binary, built with `go test -c`
*.test

# Output of the go coverage tool, specifically when used with LiteIDE
*.out

# Dependency directories (remove the comment below to include it)
# vendor/
vendor/
19 changes: 17 additions & 2 deletions .goreleaser.yml
View file
Original file line number Diff line number Diff line change
@@ -1,3 +1,17 @@
# Copyright 2021 The Kubermatic Kubernetes Platform contributors.
#
# 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.

project_name: gman

builds:
Expand All @@ -14,9 +28,10 @@ archives:
- id: gman
format: zip
files:
- README.md
- CHANGELOG.md
- Configuration.md
- LICENSE
- config.example.yaml
- README.md

release:
prerelease: true
Expand Down
13 changes: 12 additions & 1 deletion CHANGELOG.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,18 @@

All notable changes to this module will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
## [v0.5.0] - 2021-02-04

* improved license handling speed
* allow to omit default values
* auotmatic sorting
* removed `secondaryEmailAddress`, relying on aliases instead
* list of possible licenses can be overwritten (insetad of relying
on the built-in licenses)
* removed orgUnitPath from orgUnit configuration, as it is always
deduced from the name anyway and cannot be changed
* user, group and org unit configuration files must now always be
given, but they can be the same file

## [v0.0.7] - 2021-01-06

Expand Down
4 changes: 2 additions & 2 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ Origin (DCO). This document was created by the Linux Kernel community and is a
simple statement that you, as a contributor, have the legal right to make the
contribution. See the [DCO](DCO) file for details.

Any copyright notices in this repo should specify the authors as "the Kubermatic Gman project contributors".
Any copyright notices in this repo should specify the authors as "the Kubermatic GMan project contributors".

To sign your work, just add a line like this at the end of your commit message:

Expand All @@ -26,7 +26,7 @@ By doing this you state that you can certify the following (from https://develop

## Email and Chat

The Gman project currently uses the general Kubermatic email list and Slack channel:
The GMan project currently uses the general Kubermatic email list and Slack channel:
- Email: [Kubermatic-dev](https://groups.google.com/forum/#!forum/kubermatic-dev)
- Slack: #[Slack](http://slack.kubermatic.io/) on Slack

Expand Down
277 changes: 118 additions & 159 deletions Configuration.md
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Configuration
# Configuration

*Here can be found all the configuration details of Gman.*
*Here are the configuration details of GMan.*

**Table of contents:**
<!-- TOC -->
Expand All @@ -9,170 +9,129 @@
- [Users](#users)
- [User Licenses](#user-licenses)
- [Groups](#groups)
- [Group's Permissions](#groups-permissions)
- [Contacting owner](#contacting-owner)
- [Viewing membership](#viewing-membership)
- [Approving membership](#approving-membership)
- [Posting messages](#posting-messages)
- [Joining group](#joining-group)
<!-- /TOC -->

## Organizational Units

The organizational units are specified as the entries of the `org_units` collection.

Each OU contains:

| parameter | type | description | required |
|--------------|--------|--------------|----------|
| name | string | The name of the organizational unit. Inside of the OU's path it is the last entry, i.e. an organizational unit's name within the `/students/math/extended_math` parent path is `extended_math` | yes |
| description | string | The description of the organizational unit. | no |
| parentOrgUnitPath | string | The organizational unit's parent path. If the OU is directly under the parent organization, the entry should contain a single slash `/`. If OU is nested, then, for example, `/students/mathematics` is the parent path for `extended_math` organizational unit with full path `/students/math/extended_math`. | yes |
| org_unit_path | string | The full path of the OU. It is derived from parentOrgUnitPath and organizational unit's name. | yes |

## Users

The users are specified as the entries of the `users` collection.

Each user contains:

| parameter | type | description | required |
|------------|--------|--------------|----------|
| given_name | string | first name of the user | yes |
| family_name | string | last name of the user | yes |
| primary_email | string | a GSuite email address; must end with your domain name | yes |
| secondary_email | string | additional, private email address | no |
| org_unit_path | string | org unit path indicates in which OU the user should be created; single slash '/' points to parent organization | no |
| aliases | list of strings | list of the user's alias email addresses | no |
| phones | list of strings | list of the user's phone numbers | no |
| recovery_phone | string | recovery phone of the user | no |
| recovery_email | string | recovery email of the user; allows password recovery for the users | no |
| licenses | list of strings | Google products and related Stock Keeping Units (SKUs) assigned to the user; for detailed information about possible values, see table below | no |
| employee_info: employee_ID | string | employee ID | no |
| employee_info: department | string | department | no |
| employee_info: job_title | string | title of the work position | no |
| employee_info: type | string | description of the employment type | no |
| employee_info: cost_center | string | cost center of the user's organization | no |
| employee_info: manager_email | string | email of the person (manager) the user is related to | no |
| location: building | string | building name | no |
| location: floor | string | floor name/number | no |
| location: floor_section | string | floor section | no |
| addresses | string | private address of the user | no |

### User Licenses
The organizational units (OU) are specified as the entries of the `orgUnits` collection.

```yaml
organization: exampleorg
orgUnits:
- # unique name (required)
name: Org Unit 1
description: An optional description text.
# The organizational unit's parent path.
# If the OU is directly under the parent organization, the entry should contain a single slash `/`
# (which is also the default)
parentOrgUnitPath: /
blockInheritance: false

- ...
```
## Users
The users are specified as the entries of the `users` collection.

```yaml
organization: exampleorg
users:
- # first name of the user (required)
givenName: Roxy
# last name of the user (required)
familyName: Sampleperson
# a GSuite email address; must end with your domain name (required)
primaryEmail: [email protected]
# org unit path indicates in which OU the user should be created;
# single slash '/' points to parent organization (default)
orgUnitPath: /AwesomePeople
# optional list of additional email aliases
aliases:
- [email protected]
# optional list of phone numbers
phones:
- 555-887951-87
# recovery phone number (optional)
recoveryPhone: 555-887951-87
# recovery email address (optional)
recoveryEmail: [email protected]
# list of licenses this user is assigned to
licenses:
- GoogleDriveStorage20GB
- GoogleVoicePremier
# optional detailed employee information
employee:
# employee ID
id: ''
department: ''
jobTitle: ''
type: ''
costCenter: ''
managerEmail: ''
# optional location info
location:
building: ''
floor: ''
floorSection: ''
# optional address
address: "Rue d'Example 42, 12345 Sampleville"
- ...
```

### User Licenses

The user's licenses are the Google products and related Stock Keeping Units (SKUs).
The official list of all the available products can be found in [the official Google documentation](https://developers.google.com/admin-sdk/licensing/v1/how-tos/products).

Gman supports the following names as the equivalents of the Google SKUs:

| Google SKU Name (License) | Gman value |
|---------------------------|------------|
| G Suite Enterprise | GSuiteEnterprise |
| G Suite Business | GSuiteBusiness |
| G Suite Basic | GSuiteBasic
| G Suite Essentials | GSuiteEssentials |
| G Suite Lite | GSuiteLite |
| Google Apps Message Security | GoogleAppsMessageSecurity |
| G Suite Enterprise for Education | GSuiteEducation |
| G Suite Enterprise for Education (Student) | GSuiteEducationStudent |
| Google Drive storage 20 GB | GoogleDrive20GB |
| Google Drive storage 50 GB | GoogleDrive50GB |
| Google Drive storage 200 GB | GoogleDrive200GB |
| Google Drive storage 400 GB | GoogleDrive400GB |
| Google Drive storage 1 TB | GoogleDrive1TB |
| Google Drive storage 2 TB | GoogleDrive2TB |
| Google Drive storage 4 TB | GoogleDrive4TB |
| Google Drive storage 8 TB | GoogleDrive8TB |
| Google Drive storage 16 TB | GoogleDrive16TB |
| Google Vault | GoogleVault |
| Google Vault - Former Employee | GoogleVaultFormerEmployee |
| Cloud Identity Premium | CloudIdentityPremium |
| Google Voice Starter | GoogleVoiceStarter |
| Google Voice Standard | GoogleVoiceStandard |
| Google Voice Premier | GoogleVoicePremier |

Remark: *Cloud Identity Free Edition* is a site-wide SKU (applied at customer level), hence it cannot be managed by Gman as it is not assigned to individual users.
The official list of all the available products can be found in [the official Google documentation](https://developers.google.com/admin-sdk/licensing/v1/how-tos/products).

## Groups

The groups are specified as the entries of the `groups` collection.

Each user contains:

| parameter | type | description | required |
|-----------|------|-------------|----------|
| name | string | name of the group | yes |
| email | string | email of the group; must end with your organization's domain name | yes |
| description | string | group's description; max 300 characters |
| who_can_contact_owner | string | permissions to view contact owner of the group; for possible values see below | yes |
| who_can_view_members | string | permissions to view group messages; for possible values see below | yes |
| who_can_approve_members | string | permissions to approve members who ask to join groups; for possible values see below | yes |
| who_can_post | string | permissions to post messages; for possible values see below | yes |
| who_can_join | string | permissions to join group; for possible values see below | yes |
| allow_external_members | bool | identifies whether members external to your organization can join the group | yes |
| is_archived | bool | allows the group content to be archived | yes |
| members | list of members | each member is specified by the email and the role; for the limits of numebr of users please refer to [the official Google documentation](https://support.google.com/a/answer/6099642?hl=en) | yes |
| member: email | string | primary email of the user | yes |
| member: role | string | role in the group of the user; possible values are: `MEMBER`, `OWNER` or `MANAGER` | yes |

### Group's Permissions

The group permissions designate who can perform which actions in the group.

#### Contacting owner

Permission to contact owner of the group via web UI. Field name is `who_can_contact_owner`. The entered values are case sensitive.

| possible value | description |
|----------------|-------------|
| ALL_IN_DOMAIN_CAN_CONTACT | all users in the domain |
| ALL_MANAGERS_CAN_CONTACT | only managers of the group |
| ALL_MEMBERS_CAN_CONTACT | only members of the group |
| ANYONE_CAN_CONTACT | any Internet user |

#### Viewing membership
GMan has a list of licenses built-in, but this can be overwritten by running gman with
`-licenses-config <file>`, which must be a YAML file that contains a list of licenses.
Run GMan with `-licenses` to see the list of default licenses. If you also specify
`-licenses-yaml`, you get an output that can be directly used as a config file.

Permissions to view group members. Field name is `who_can_view_members`. The entered values are case sensitive.
Remark: *Cloud Identity Free Edition* is a site-wide SKU (applied at customer level),
hence it cannot be managed by GMan as it is not assigned to individual users.

| possible value | description |
|----------------|-------------|
| ALL_IN_DOMAIN_CAN_VIEW | all users in the domain |
| ALL_MANAGERS_CAN_VIEW | only managers of the group |
| ALL_MEMBERS_CAN_VIEW | only members of the group |
| ANYONE_CAN_VIEW | anyone in the group |

#### Approving membership

Permissions to approve members who ask to join group. Field name is `who_can_approve_members`. The entered values are case sensitive.

| possible value | description |
|----------------|-------------|
| ALL_OWNERS_CAN_APPROVE | only owners of the group |
| ALL_MANAGERS_CAN_APPROVE | only managers of the group |
| ALL_MEMBERS_CAN_APPROVE | only members of the group |
| NONE_CAN_APPROVE | noone in the group |

#### Posting messages

Permissions to post messages in the group. Field name is `who_can_post`. The entered values are case sensitive.

| possible value | description |
|----------------|-------------|
| NONE_CAN_POST | the group is disabled and archived; 'is_archived' must be set to true, otherwise will result in an error |
| ALL_MANAGERS_CAN_POST | only managers and owners of the group |
| ALL_MEMBERS_CAN_POST | only members of the group |
| ALL_OWNERS_CAN_POST | only owners of the group |
| ALL_IN_DOMAIN_CAN_POST | anyone in the organization |
| ANYONE_CAN_POST | any Internet user who can access your Google Groups service |

#### Joining group

Permissions to join the group. Field name is `who_can_join`. The entered values are case sensitive.
## Groups

| possible value | description |
|----------------|-------------|
| ANYONE_CAN_JOIN | any Internet user who can access your Google Groups service |
| ALL_IN_DOMAIN_CAN_JOIN | anyone in the organization |
| INVITED_CAN_JOIN | only invited candidates |
| CAN_REQUEST_TO_JOIN | non-members can request an invitation to join |
The groups are specified as the entries of the `groups` collection.

```yaml
organization: exampleorg
groups:
- # unique name (required)
name: Christmas 2021
# group email address (required)
email: [email protected]
# the following settings control access to the group;
# the shown value is the implicit default value
# one of ALL_MANAGERS_CAN_CONTACT, ALL_MEMBERS_CAN_CONTACT, ALL_IN_DOMAIN_CAN_CONTACT, ANYONE_CAN_CONTACT
whoCanContactOwner: ALL_MANAGERS_CAN_CONTACT
# one of ALL_MANAGERS_CAN_VIEW, ALL_MEMBERS_CAN_VIEW, ALL_IN_DOMAIN_CAN_VIEW
whoCanViewMembership: ALL_MEMBERS_CAN_VIEW
# one of ALL_MANAGERS_CAN_APPROVE, ALL_OWNERS_CAN_APPROVE, ALL_MEMBERS_CAN_APPROVE, NONE_CAN_APPROVE
whoCanApproveMembers: ALL_MANAGERS_CAN_APPROVE
# one of NONE_CAN_POST, ALL_OWNERS_CAN_POST, ALL_MANAGERS_CAN_POST, ALL_MEMBERS_CAN_POST, ALL_IN_DOMAIN_CAN_POST, ANYONE_CAN_POST
whoCanPostMessage: ALL_MEMBERS_CAN_POST
# one of INVITED_CAN_JOIN, CAN_REQUEST_TO_JOIN, ALL_IN_DOMAIN_CAN_JOIN, ANYONE_CAN_JOIN
whoCanJoin: INVITED_CAN_JOIN
# whether external users can join the group
allowExternalMembers: false
# whether the group is archived (readonly)
isArchived: false
# list of members in this group
members:
- email: [email protected]
- email: [email protected]
- email: [email protected]
# each member must be either OWNER, MANAGER or MEMBER (default)
role: OWNER
- ...
```
Loading

0 comments on commit 8482ac7

Please sign in to comment.