You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
243 lines
10 KiB
Python
243 lines
10 KiB
Python
# 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.
|
|
|
|
from gslib.help_provider import HELP_NAME
|
|
from gslib.help_provider import HELP_NAME_ALIASES
|
|
from gslib.help_provider import HELP_ONE_LINE_SUMMARY
|
|
from gslib.help_provider import HelpProvider
|
|
from gslib.help_provider import HELP_TEXT
|
|
from gslib.help_provider import HelpType
|
|
from gslib.help_provider import HELP_TYPE
|
|
|
|
_detailed_help_text = ("""
|
|
<B>OVERVIEW</B>
|
|
Versioning-enabled buckets maintain an archive of objects, providing a way to
|
|
un-delete data that you accidentally deleted, or to retrieve older versions of
|
|
your data. You can turn versioning on or off for a bucket at any time. Turning
|
|
versioning off leaves existing object versions in place, and simply causes the
|
|
bucket to stop accumulating new object versions. In this case, if you upload
|
|
to an existing object the current version is overwritten instead of creating
|
|
a new version.
|
|
|
|
Regardless of whether you have enabled versioning on a bucket, every object
|
|
has two associated positive integer fields:
|
|
- the generation, which is updated when the content of an object is
|
|
overwritten.
|
|
- the meta-generation, which identifies the metadata generation. It starts
|
|
at 1; is updated every time the metadata (e.g., ACL or Content-Type) for a
|
|
given content generation is updated; and gets reset when the generation
|
|
number changes.
|
|
|
|
Of these two integers, only the generation is used when working with versioned
|
|
data. Both generation and meta-generation can be used with concurrency control
|
|
(discussed in a later section).
|
|
|
|
To work with object versioning in gsutil, you can use a flavor of storage URIs
|
|
that that embed the object generation, which we refer to as version-specific URIs.
|
|
For example, the version-less object URI:
|
|
|
|
gs://bucket/object
|
|
|
|
might have have two versions, with these version-specific URIs:
|
|
|
|
gs://bucket/object#1360383693690000
|
|
gs://bucket/object#1360383802725000
|
|
|
|
The following sections discuss how to work with versioning and concurrency
|
|
control.
|
|
|
|
|
|
<B>OBJECT VERSIONING</B>
|
|
You can view, enable, and disable object versioning on a bucket using
|
|
the getversioning and setversioning commands. For example:
|
|
|
|
gsutil setversioning on gs://bucket
|
|
|
|
will enable versioning for the named bucket. See 'gsutil help getversioning'
|
|
and 'gsutil help setversioning' for additional details.
|
|
|
|
To see all object versions in a versioning-enabled bucket along with
|
|
their generation.meta-generation information, use gsutil ls -a:
|
|
|
|
gsutil ls -a gs://bucket
|
|
|
|
You can also specify particular objects for which you want to find the
|
|
version-specific URI(s), or you can use wildcards:
|
|
|
|
gsutil ls -a gs://bucket/object1 gs://bucket/images/*.jpg
|
|
|
|
The generation values form a monotonically increasing sequence as you create
|
|
additional object versions. Because of this, the latest object version is
|
|
always the last one listed in the gsutil ls output for a particular object.
|
|
For example, if a bucket contains these three versions of gs://bucket/object:
|
|
|
|
gs://bucket/object#1360035307075000
|
|
gs://bucket/object#1360101007329000
|
|
gs://bucket/object#1360102216114000
|
|
|
|
then gs://bucket/object#1360102216114000 is the latest version and
|
|
gs://bucket/object#1360035307075000 is the oldest available version.
|
|
|
|
If you specify version-less URIs with gsutil, you will operate on the
|
|
latest not-deleted version of an object, for example:
|
|
|
|
gsutil cp gs://bucket/object ./dir
|
|
|
|
or
|
|
|
|
gsutil rm gs://bucket/object
|
|
|
|
To operate on a specific object version, use a version-specific URI.
|
|
For example, suppose the output of the above gsutil ls -a command is:
|
|
|
|
gs://bucket/object#1360035307075000
|
|
gs://bucket/object#1360101007329000
|
|
|
|
In this case, the command:
|
|
|
|
gsutil cp gs://bucket/object#1360035307075000 ./dir
|
|
|
|
will retrieve the second most recent version of the object.
|
|
|
|
Note that version-specific URIs cannot be the target of the gsutil cp
|
|
command (trying to do so will result in an error), because writing to a
|
|
versioned object always creates a new version.
|
|
|
|
If an object has been deleted, it will not show up in a normal gsutil ls
|
|
listing (i.e., ls without the -a option). You can restore a deleted object by
|
|
running gsutil ls -a to find the available versions, and then copying one of
|
|
the version-specific URIs to the version-less URI, for example:
|
|
|
|
gsutil cp gs://bucket/object#1360101007329000 gs://bucket/object
|
|
|
|
Note that when you do this it creates a new object version, which will incur
|
|
additional charges. You can get rid of the extra copy by deleting the older
|
|
version-specfic object:
|
|
|
|
gsutil rm gs://bucket/object#1360101007329000
|
|
|
|
Or you can combine the two steps by using the gsutil mv command:
|
|
|
|
gsutil mv gs://bucket/object#1360101007329000 gs://bucket/object
|
|
|
|
If you want to remove all versions of an object use the gsutil rm -a option:
|
|
|
|
gsutil rm -a gs://bucket/object
|
|
|
|
Note that there is no limit to the number of older versions of an object you
|
|
will create if you continue to upload to the same object in a versioning-
|
|
enabled bucket. It is your responsibility to delete versions beyond the ones
|
|
you want to retain.
|
|
|
|
|
|
<B>CONCURRENCY CONTROL</B>
|
|
If you are building an application using Google Cloud Storage, you may need to
|
|
be careful about concurrency control. Normally gsutil itself isn't used for
|
|
this purpose, but it's possible to write scripts around gsutil that perform
|
|
concurrency control.
|
|
|
|
For example, suppose you want to implement a "rolling update" system using
|
|
gsutil, where a periodic job computes some data and uploads it to the cloud.
|
|
On each run, the job starts with the data that it computed from last run, and
|
|
computes a new value. To make this system robust, you need to have multiple
|
|
machines on which the job can run, which raises the possibility that two
|
|
simultaneous runs could attempt to update an object at the same time. This
|
|
leads to the following potential race condition:
|
|
- job 1 computes the new value to be written
|
|
- job 2 computes the new value to be written
|
|
- job 2 writes the new value
|
|
- job 1 writes the new value
|
|
|
|
In this case, the value that job 1 read is no longer current by the time
|
|
it goes to write the updated object, and writing at this point would result
|
|
in stale (or, depending on the application, corrupt) data.
|
|
|
|
To prevent this, you can find the version-specific name of the object that was
|
|
created, and then use the information contained in that URI to specify an
|
|
x-goog-if-generation-match header on a subsequent gsutil cp command. You can
|
|
do this in two steps. First, use the gsutil cp -v option at upload time to get
|
|
the version-specific name of the object that was created, for example:
|
|
|
|
gsutil cp -v file gs://bucket/object
|
|
|
|
might output:
|
|
|
|
Created: gs://bucket/object#1360432179236000
|
|
|
|
You can extract the generation value from this object and then construct a
|
|
subsequent gsutil command like this:
|
|
|
|
gsutil -h x-goog-if-generation-match:1360432179236000 cp newfile \\
|
|
gs://bucket/object
|
|
|
|
This command requests Google Cloud Storage to attempt to upload newfile
|
|
but to fail the request if the generation of newfile that is live at the
|
|
time of the upload does not match that specified.
|
|
|
|
If the command you use updates object metadata, you will need to find the
|
|
current meta_generation for an object. To do this, use the gsutil ls -a and
|
|
-l options. For example, the command:
|
|
|
|
gsutil ls -l -a gs://bucket/object
|
|
|
|
will output something like:
|
|
|
|
64 2013-02-12T19:59:13 gs://bucket/object#1360699153986000 meta_generation=3
|
|
1521 2013-02-13T02:04:08 gs://bucket/object#1360721048778000 meta_generation=2
|
|
|
|
Given this information, you could use the following command to request setting
|
|
the ACL on the older version of the object, such that the command will fail
|
|
unless that is the current version of the data+metadata:
|
|
|
|
gsutil -h x-goog-if-generation-match:1360699153986000 -h \\
|
|
x-goog-if-metageneration-match:3 setacl public-read \\
|
|
gs://bucket/object#1360699153986000
|
|
|
|
Without adding these headers, the update would simply overwrite the existing
|
|
ACL. Note that in contrast, the gsutil chacl command uses these headers
|
|
automatically, because it performs a read-modify-write cycle in order to edit
|
|
ACLs.
|
|
|
|
If you want to experiment with how generations and metagenerations work, try
|
|
the following. First, upload an object; then use gsutil ls -l -a to list all
|
|
versions of the object, along with each version's meta_generation; then re-
|
|
upload the object and repeat the gsutil ls -l -a. You should see two object
|
|
versions, each with meta_generation=1. Now try setting the ACL, and rerun the
|
|
gsutil ls -l -a. You should see the most recent object generation now has
|
|
meta_generation=2.
|
|
|
|
|
|
<B>FOR MORE INFORMATION</B>
|
|
For more details on how to use versioning and preconditions, see
|
|
https://developers.google.com/storage/docs/object-versioning
|
|
""")
|
|
|
|
|
|
class CommandOptions(HelpProvider):
|
|
"""Additional help about object versioning."""
|
|
|
|
help_spec = {
|
|
# Name of command or auxiliary help info for which this help applies.
|
|
HELP_NAME : 'versioning',
|
|
# List of help name aliases.
|
|
HELP_NAME_ALIASES : ['concurrency', 'concurrency control', 'versioning',
|
|
'versions'],
|
|
# Type of help:
|
|
HELP_TYPE : HelpType.ADDITIONAL_HELP,
|
|
# One line summary of this help.
|
|
HELP_ONE_LINE_SUMMARY : 'Working with object versions; concurrency control',
|
|
# The full help text.
|
|
HELP_TEXT : _detailed_help_text,
|
|
}
|