.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Podwrapper::Man 1.38.2 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "nbdkit-gcs-plugin 1"
.TH nbdkit-gcs-plugin 1 2024-05-10 nbdkit-1.38.2 NBDKIT
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
nbdkit\-gcs\-plugin \- expose data in Google Cloud Storage (GCS) buckets
as block device
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 3
\& nbdkit gcs [json\-credentials=FILE]
\&            [size=NN object\-size=NN]
\&            bucket=BUCKET key=STRING
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
\&\f(CW\*(C`nbdkit\-gcs\-plugin\*(C'\fR is a plugin for \fBnbdkit\fR\|(1) which lets you open
objects stored in Google Cloud Storage (GCS) as disk images.
.PP
This plugin uses the Python Google Cloud Storage client library
(google-cloud-storage).
It requires Python ≥ 3.7.
.SH EXAMPLES
.IX Header "EXAMPLES"
.Vb 2
\& nbdkit gcs json\-credentials=/path/to\-my\-json\-credentials.json \e
\&            bucket=MY\-BUCKET key=disk.img
.Ve
.PP
Provides a read only block device holding the data contained in the
\&\fIdisk.img\fR object.
.PP
.Vb 3
\& nbdkit gcs json\-credentials=/path/to\-my\-json\-credentials.json \e
\&            size=50G object\-size=128k \e
\&            bucket=MY\-BUCKET key=disk
.Ve
.PP
Provides a read-write block device with size 50G, whose contents are
stored across multiple in objects of size 128k, prefixed with \fIdisk/\fR
.SH PARAMETERS
.IX Header "PARAMETERS"
.IP \fBjson\-credentials=\fRFILE 4
.IX Item "json-credentials=FILE"
Path to a JSON file with Google Service account keys. Application Default
Credentials will be used if \f(CW\*(C`json\-credentials\*(C'\fR is not specified (see
"CREDENTIALS" below).
.IP \fBbucket=\fRBUCKET 4
.IX Item "bucket=BUCKET"
The bucket containing the object(s).  This parameter is required.
.IP \fBkey=\fRSTRING 4
.IX Item "key=STRING"
The object name (if \f(CW\*(C`size\*(C'\fR is not specified) or object prefix (if
\&\f(CW\*(C`size\*(C'\fR is specified) to use within the bucket.  This parameter is
required.
.IP \fBsize=\fRSIZE 4
.IX Item "size=SIZE"
.PD 0
.IP \fBobject\-size=\fRSIZE 4
.IX Item "object-size=SIZE"
.PD
These two parameters must always be specified together. If set, data
will be split into blocks of \f(CW\*(C`object\-size\*(C'\fR and stored as separate
objects. The block device will report a total size of \f(CW\*(C`size\*(C'\fR and be
writeable and trim-able.
.Sp
Object names will have the form \fIkey/%16x\fR, where \f(CW%16x\fR is the
16\-digit hexadecimal block number. If there are existing objects under
the prefix that do not have the expected size, the plugin will crash.
.SH "PERFORMANCE CONSIDERATIONS"
.IX Header "PERFORMANCE CONSIDERATIONS"
It is highly recommended that clients do their utmost to issue
requests that exactly match the object size: Smaller write requests
will incur a performance penalty due to the need for read-modify-write
cycles (thus also incurring latency from two network
round-trips). Larger read and write requests will incur a performance
penalty because of sequential execution.
.PP
The \fBnbdkit\-blocksize\-filter\fR\|(1) can be used to alleviate the impact
of requests larger than the object size, but does not help if the
client issues requests smaller than the block size.
.PP
The \fBnbdkit\-stats\-filter\fR\|(1) can be used to investigate what block
sizes and alignments are used by the client.
.PP
When connecting through the Linux kernel's NBD module, consider
setting \f(CW\*(C`/sys/block/nbd<X>/queue/max_sectors_kb\*(C'\fR to match the
object size.
.SH CREDENTIALS
.IX Header "CREDENTIALS"
Refer to the following web pages:
.IP "Google Service account keys" 4
.IX Item "Google Service account keys"
https://developers.google.com/workspace/guides/create\-credentials#service\-account
.IP "Application Default Credentials" 4
.IX Item "Application Default Credentials"
https://cloud.google.com/docs/authentication/application\-default\-credentials
.SH FILES
.IX Header "FILES"
.ie n .IP \fR\fI$plugindir\fR\fI/nbdkit\-gcs\-plugin\fR 4
.el .IP \fR\f(CI$plugindir\fR\fI/nbdkit\-gcs\-plugin\fR 4
.IX Item "$plugindir/nbdkit-gcs-plugin"
The plugin.
.Sp
Use \f(CW\*(C`nbdkit \-\-dump\-config\*(C'\fR to find the location of \f(CW$plugindir\fR.
.ie n .IP \fR\fI$HOME\fR\fI/.config/gcloud/application_default_credentials.json\fR 4
.el .IP \fR\f(CI$HOME\fR\fI/.config/gcloud/application_default_credentials.json\fR 4
.IX Item "$HOME/.config/gcloud/application_default_credentials.json"
Application Default Credentials.
.SH "ENVIRONMENT VARIABLES"
.IX Header "ENVIRONMENT VARIABLES"
.ie n .IP """GOOGLE_APPLICATION_CREDENTIALS""" 4
.el .IP \f(CWGOOGLE_APPLICATION_CREDENTIALS\fR 4
.IX Item "GOOGLE_APPLICATION_CREDENTIALS"
You can use the \f(CW\*(C`GOOGLE_APPLICATION_CREDENTIALS\*(C'\fR environment variable
to provide the location of a credential JSON file.
.SH "COMPARISON TO S3 PLUGIN"
.IX Header "COMPARISON TO S3 PLUGIN"
You can use the \f(CW\*(C`S3\*(C'\fR plugin to access Google Cloud Storage in
interoperability mode.  \f(CW\*(C`read\*(C'\fR and \f(CW\*(C`write\*(C'\fR work perfectly fine,
while \f(CW\*(C`trim\*(C'\fR and \f(CW\*(C`zero\*(C'\fR operations don't work in the general case:
trimmed or zeroed-out blocks cannot be deleted from the storage using
the \f(CW\*(C`S3\*(C'\fR plugin.
.SH VERSION
.IX Header "VERSION"
\&\f(CW\*(C`nbdkit\-gcs\-plugin\*(C'\fR first appeared in nbdkit 1.38.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBnbdkit\fR\|(1),
\&\fBnbdkit\-plugin\fR\|(3),
\&\fBnbdkit\-python\-plugin\fR\|(3),
\&\fBnbdkit\-S3\-plugin\fR\|(3),
https://pypi.org/project/google\-cloud\-storage/,
https://developers.google.com/workspace/guides/create\-credentials#service\-account,
https://cloud.google.com/docs/authentication/application\-default\-credentials.
.SH AUTHORS
.IX Header "AUTHORS"
Mykola Ivanets
.SH COPYRIGHT
.IX Header "COPYRIGHT"
Copyright Infrascale Inc.
.SH LICENSE
.IX Header "LICENSE"
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:
.IP \(bu 4
Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
.IP \(bu 4
Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
.IP \(bu 4
Neither the name of Red Hat nor the names of its contributors may be
used to endorse or promote products derived from this software without
specific prior written permission.
.PP
THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR
CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
SUCH DAMAGE.