[catapult] - Copy Telemetry's gsutilz over to third_party.

third_party/gsutil/gslib/addlhelp/acls.py

+# -*- coding: utf-8 -*-
+# Copyright 2012 Google Inc. All Rights Reserved.
+#
+# 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.
+"""Additional help about Access Control Lists."""
+
+from __future__ import absolute_import
+
+from gslib.help_provider import HelpProvider
+
+_DETAILED_HELP_TEXT = ("""
+<B>OVERVIEW</B>
+  Access Control Lists (ACLs) allow you to control who can read and write
+  your data, and who can read and write the ACLs themselves.
+
+  If not specified at the time an object is uploaded (e.g., via the gsutil cp
+  -a option), objects will be created with a default object ACL set on the
+  bucket (see "gsutil help defacl"). You can replace the ACL on an object
+  or bucket using the "gsutil acl set" command, or
+  modify the existing ACL using the "gsutil acl ch" command (see "gsutil help
+  acl").
+
+
+<B>BUCKET VS OBJECT ACLS</B>
+  In Google Cloud Storage, the bucket ACL works as follows:
+
+  - Users granted READ access are allowed to list the bucket contents.
+
+  - Users granted WRITE access are allowed READ access and also are
+    allowed to write and delete objects in that bucket -- including
+    overwriting previously written objects.
+
+  - Users granted OWNER access are allowed WRITE access and also
+    are allowed to read and write the bucket's ACL.
+
+  The object ACL works as follows:
+
+  - Users granted READ access are allowed to read the object's data and
+    metadata.
+
+  - Users granted OWNER access are allowed READ access and also
+    are allowed to read and write the object's ACL.
+
+  A couple of points are worth noting, that sometimes surprise users:
+
+  1. There is no WRITE access for objects; attempting to set an ACL with WRITE
+     permission for an object will result in an error.
+
+  2. The bucket ACL plays no role in determining who can read objects; only the
+     object ACL matters for that purpose. This is different from how things
+     work in Linux file systems, where both the file and directory permission
+     control file read access. It also means, for example, that someone with
+     OWNER over the bucket may not have read access to objects in
+     the bucket.  This is by design, and supports useful cases. For example,
+     you might want to set up bucket ownership so that a small group of
+     administrators have OWNER on the bucket (with the ability to
+     delete data to control storage costs), but not grant those users read
+     access to the object data (which might be sensitive data that should
+     only be accessed by a different specific group of users).
+
+
+<B>CANNED ACLS</B>
+  The simplest way to set an ACL on a bucket or object is using a "canned
+  ACL". The available canned ACLs are:
+
+  project-private
+    Gives permission to the project team based on their roles. Anyone who is
+    part of the team has READ permission, and project owners and project editors
+    have OWNER permission. This is the default ACL for newly created
+    buckets. This is also the default ACL for newly created objects unless the
+    default object ACL for that bucket has been changed. For more details see
+    "gsutil help projects".
+
+  private
+    Gives the requester (and only the requester) OWNER permission for a
+    bucket or object.
+
+  public-read
+    Gives all users (whether logged in or anonymous) READ permission. When
+    you apply this to an object, anyone on the Internet can read the object
+    without authenticating.
+
+    NOTE: By default, publicly readable objects are served with a Cache-Control
+    header allowing such objects to be cached for 3600 seconds. If you need to
+    ensure that updates become visible immediately, you should set a
+    Cache-Control header of "Cache-Control:private, max-age=0, no-transform" on
+    such objects. For help doing this, see 'gsutil help setmeta'.
+
+    NOTE: Setting a bucket ACL to public-read will remove all OWNER and WRITE
+    permissions from everyone except the project owner group. Setting an object
+    ACL to public-read will remove all OWNER and WRITE permissions from
+    everyone except the object owner. For this reason, we recommend using
+    the "acl ch" command to make these changes; see "gsutil help acl ch" for
+    details.
+
+  public-read-write
+    Gives all users READ and WRITE permission. This ACL applies only to buckets.
+    NOTE: Setting a bucket to public-read-write will allow anyone on the
+    Internet to upload anything to your bucket. You will be responsible for this
+    content.
+
+    NOTE: Setting a bucket ACL to public-read-write will remove all OWNER
+    permissions from everyone except the project owner group. Setting an object
+    ACL to public-read-write will remove all OWNER permissions from
+    everyone except the object owner. For this reason, we recommend using
+    the "acl ch" command to make these changes; see "gsutil help acl ch" for
+    details.
+
+  authenticated-read
+    Gives the requester OWNER permission and gives all authenticated
+    Google account holders READ permission.
+
+  bucket-owner-read
+    Gives the requester OWNER permission and gives the bucket owner READ
+    permission. This is used only with objects.
+
+  bucket-owner-full-control
+    Gives the requester OWNER permission and gives the bucket owner
+    OWNER permission. This is used only with objects.
+
+
+<B>ACL JSON</B>
+  When you use a canned ACL, it is translated into an JSON representation
+  that can later be retrieved and edited to specify more fine-grained
+  detail about who can read and write buckets and objects. By running
+  the "gsutil acl get" command you can retrieve the ACL JSON, and edit it to
+  customize the permissions.
+
+  As an example, if you create an object in a bucket that has no default
+  object ACL set and then retrieve the ACL on the object, it will look
+  something like this:
+
+  [
+    {
+      "entity": "group-00b4903a9740e42c29800f53bd5a9a62a2f96eb3f64a4313a115df3f3a776bf7",
+      "entityId": "00b4903a9740e42c29800f53bd5a9a62a2f96eb3f64a4313a115df3f3a776bf7",
+      "role": "OWNER"
+    },
+    {
+      "entity": "group-00b4903a977fd817e9da167bc81306489181a110456bb635f466d71cf90a0d51",
+      "entityId": "00b4903a977fd817e9da167bc81306489181a110456bb635f466d71cf90a0d51",
+      "role": "OWNER"
+    },
+    {
+      "entity": "00b4903a974898cc8fc309f2f2835308ba3d3df1b889d3fc7e33e187d52d8e71",
+      "entityId": "00b4903a974898cc8fc309f2f2835308ba3d3df1b889d3fc7e33e187d52d8e71",
+      "role": "READER"
+    }
+  ]
+
+  The ACL consists collection of elements, each of which specifies an Entity
+  and a Role.  Entities are the way you specify an individual or group of
+  individuals, and Roles specify what access they're permitted.
+
+  This particular ACL grants OWNER to two groups (which means members
+  of those groups are allowed to read the object and read and write the ACL),
+  and READ permission to a third group. The project groups are (in order)
+  the project owners group, editors group, and viewers group.
+
+  The 64 digit hex identifiers (following any prefixes like "group-") used in
+  this ACL are called canonical IDs.  They are used to identify predefined
+  groups associated with the project that owns the bucket: the Project Owners,
+  Project Editors, and All Project Team Members groups. For more information
+  the permissions and roles of these project groups, see "gsutil help projects".
+
+  Here's an example of an ACL specified using the group-by-email and
+  group-by-domain entities:
+
+[
+  {
+    "entity": "group-travel-companion-owners@googlegroups.com"
+    "email": "travel-companion-owners@googlegroups.com",
+    "role": "OWNER",
+  }
+  {
+    "domain": "example.com",
+    "entity": "domain-example.com"
+    "role": "READER",
+  },
+]
+
+  This ACL grants members of an email group OWNER, and grants READ
+  access to any user in a domain (which must be a Google Apps for Business
+  domain). By applying email group grants to a collection of objects
+  you can edit access control for large numbers of objects at once via
+  http://groups.google.com. That way, for example, you can easily and quickly
+  change access to a group of company objects when employees join and leave
+  your company (i.e., without having to individually change ACLs across
+  potentially millions of objects).
+
+
+<B>SHARING SCENARIOS</B>
+  For more detailed examples how to achieve various useful sharing use
+  cases see https://developers.google.com/storage/docs/collaboration
+""")
+
+
+class CommandOptions(HelpProvider):
+  """Additional help about Access Control Lists."""
+
+  # Help specification. See help_provider.py for documentation.
+  help_spec = HelpProvider.HelpSpec(
+      help_name='acls',
+      help_name_aliases=[
+          'ACL', 'access control', 'access control list', 'authorization',
+          'canned', 'canned acl'],
+      help_type='additional_help',
+      help_one_line_summary='Working With Access Control Lists',
+      help_text=_DETAILED_HELP_TEXT,
+      subcommand_help_text={},
+  )