.TH "GCLOUD_BETA_PUBSUB_SUBSCRIPTIONS_CREATE" 1



.SH "NAME"
.HP
gcloud beta pubsub subscriptions create \- creates one or more Cloud Pub/Sub subscriptions



.SH "SYNOPSIS"
.HP
\f5gcloud beta pubsub subscriptions create\fR \fISUBSCRIPTION\fR [\fISUBSCRIPTION\fR\ ...] (\fB\-\-topic\fR=\fITOPIC\fR\ :\ \fB\-\-topic\-project\fR=\fITOPIC_PROJECT\fR) [\fB\-\-ack\-deadline\fR=\fIACK_DEADLINE\fR] [\fB\-\-enable\-exactly\-once\-delivery\fR] [\fB\-\-enable\-message\-ordering\fR] [\fB\-\-expiration\-period\fR=\fIEXPIRATION_PERIOD\fR] [\fB\-\-labels\fR=[\fIKEY\fR=\fIVALUE\fR,...]] [\fB\-\-message\-filter\fR=\fIMESSAGE_FILTER\fR] [\fB\-\-message\-retention\-duration\fR=\fIMESSAGE_RETENTION_DURATION\fR] [\fB\-\-message\-transforms\-file\fR=\fIMESSAGE_TRANSFORMS_FILE\fR] [\fB\-\-retain\-acked\-messages\fR] [[\fB\-\-bigquery\-table\fR=\fIBIGQUERY_TABLE\fR\ :\ \fB\-\-bigquery\-service\-account\-email\fR=\fIBIGQUERY_SERVICE_ACCOUNT_EMAIL\fR\ \fB\-\-drop\-unknown\-fields\fR\ \fB\-\-write\-metadata\fR\ \fB\-\-use\-table\-schema\fR\ |\ \fB\-\-use\-topic\-schema\fR]\ |\ [\fB\-\-cloud\-storage\-bucket\fR=\fICLOUD_STORAGE_BUCKET\fR\ :\ \fB\-\-cloud\-storage\-file\-datetime\-format\fR=\fICLOUD_STORAGE_FILE_DATETIME_FORMAT\fR\ \fB\-\-cloud\-storage\-file\-prefix\fR=\fICLOUD_STORAGE_FILE_PREFIX\fR\ \fB\-\-cloud\-storage\-file\-suffix\fR=\fICLOUD_STORAGE_FILE_SUFFIX\fR\ \fB\-\-cloud\-storage\-max\-bytes\fR=\fICLOUD_STORAGE_MAX_BYTES\fR\ \fB\-\-cloud\-storage\-max\-duration\fR=\fICLOUD_STORAGE_MAX_DURATION\fR\ \fB\-\-cloud\-storage\-max\-messages\fR=\fICLOUD_STORAGE_MAX_MESSAGES\fR\ \fB\-\-cloud\-storage\-output\-format\fR=\fIOUTPUT_FORMAT\fR;\ default="text"\ \fB\-\-cloud\-storage\-service\-account\-email\fR=\fICLOUD_STORAGE_SERVICE_ACCOUNT_EMAIL\fR\ \fB\-\-cloud\-storage\-use\-topic\-schema\fR\ \fB\-\-cloud\-storage\-write\-metadata\fR]] [\fB\-\-max\-delivery\-attempts\fR=\fIMAX_DELIVERY_ATTEMPTS\fR\ [\fB\-\-dead\-letter\-topic\fR=\fIDEAD_LETTER_TOPIC\fR\ :\ \fB\-\-dead\-letter\-topic\-project\fR=\fIDEAD_LETTER_TOPIC_PROJECT\fR]] [\fB\-\-max\-retry\-delay\fR=\fIMAX_RETRY_DELAY\fR\ \fB\-\-min\-retry\-delay\fR=\fIMIN_RETRY_DELAY\fR] [\fB\-\-push\-auth\-service\-account\fR=\fISERVICE_ACCOUNT_EMAIL\fR\ \fB\-\-push\-auth\-token\-audience\fR=\fIOPTIONAL_AUDIENCE_OVERRIDE\fR\ \fB\-\-push\-endpoint\fR=\fIPUSH_ENDPOINT\fR\ [\fB\-\-push\-no\-wrapper\fR\ :\ \fB\-\-push\-no\-wrapper\-write\-metadata\fR]] [\fIGCLOUD_WIDE_FLAG\ ...\fR]



.SH "DESCRIPTION"

\fB(BETA)\fR Creates one or more Cloud Pub/Sub subscriptions for a given topic.
The new subscription defaults to a PULL subscription unless a push endpoint is
specified.



.SH "POSITIONAL ARGUMENTS"

.RS 2m
.TP 2m

Subscription resource \- One or more subscriptions to create. This represents a
Cloud resource. (NOTE) Some attributes are not given arguments in this group but
can be set in other ways.

To set the \f5project\fR attribute:
.RS 2m
.IP "\(em" 2m
provide the argument \f5subscription\fR on the command line with a fully
specified name;
.IP "\(em" 2m
provide the argument \f5\-\-project\fR on the command line;
.IP "\(em" 2m
set the property \f5core/project\fR.
.RE
.sp

This must be specified.


.RS 2m
.TP 2m
\fISUBSCRIPTION\fR [\fISUBSCRIPTION\fR ...]

IDs of the subscriptions or fully qualified identifiers for the subscriptions.

To set the \f5subscription\fR attribute:
.RS 2m
.IP "\(bu" 2m
provide the argument \f5subscription\fR on the command line.
.RE
.sp


.RE
.RE
.sp

.SH "REQUIRED FLAGS"

.RS 2m
.TP 2m

Topic resource \- Name of the topic from which this subscription is receiving
messages. Each subscription is attached to a single topic. The arguments in this
group can be used to specify the attributes of this resource.

This must be specified.


.RS 2m
.TP 2m
\fB\-\-topic\fR=\fITOPIC\fR

ID of the topic or fully qualified identifier for the topic.

To set the \f5topic\fR attribute:
.RS 2m
.IP "\(bu" 2m
provide the argument \f5\-\-topic\fR on the command line.
.RE
.sp

This flag argument must be specified if any of the other arguments in this group
are specified.

.TP 2m
\fB\-\-topic\-project\fR=\fITOPIC_PROJECT\fR

Project ID of the Google Cloud project for the topic.

To set the \f5project\fR attribute:
.RS 2m
.IP "\(bu" 2m
provide the argument \f5\-\-topic\fR on the command line with a fully specified
name;
.IP "\(bu" 2m
provide the argument \f5\-\-topic\-project\fR on the command line;
.IP "\(bu" 2m
provide the argument \f5\-\-project\fR on the command line;
.IP "\(bu" 2m
set the property \f5core/project\fR.
.RE
.sp


.RE
.RE
.sp

.SH "OPTIONAL FLAGS"

.RS 2m
.TP 2m
\fB\-\-ack\-deadline\fR=\fIACK_DEADLINE\fR

The number of seconds the system will wait for a subscriber to acknowledge
receiving a message before re\-attempting delivery.

.TP 2m
\fB\-\-enable\-exactly\-once\-delivery\fR

Whether or not to enable exactly\-once delivery on the subscription. If true,
Pub/Sub provides the following guarantees for the delivery of a message with a
given value of \f5message_id\fR on this subscription: The message sent to a
subscriber is guaranteed not to be resent before the message's acknowledgment
deadline expires. An acknowledged message will not be resent to a subscriber.
Use \-\-no\-enable\-exactly\-once\-delivery to disable this flag.

.TP 2m
\fB\-\-enable\-message\-ordering\fR

Whether to receive messages with the same ordering key in order. If set,
messages with the same ordering key are sent to subscribers in the order that
Pub/Sub receives them. Use \-\-no\-enable\-message\-ordering to disable this
flag.

.TP 2m
\fB\-\-expiration\-period\fR=\fIEXPIRATION_PERIOD\fR

The subscription will expire if it is inactive for the given period. Valid
values are strings of the form INTEGER[UNIT], where UNIT is one of "s", "m",
"h", and "d" for seconds, minutes, hours, and days, respectively. If the unit is
omitted, seconds is assumed. This flag additionally accepts the special value
"never" to indicate that the subscription will never expire.

.TP 2m
\fB\-\-labels\fR=[\fIKEY\fR=\fIVALUE\fR,...]

List of label KEY=VALUE pairs to add.

Keys must start with a lowercase character and contain only hyphens (\f5\-\fR),
underscores (\f5_\fR), lowercase characters, and numbers. Values must contain
only hyphens (\f5\-\fR), underscores (\f5_\fR), lowercase characters, and
numbers.

.TP 2m
\fB\-\-message\-filter\fR=\fIMESSAGE_FILTER\fR

Expression to filter messages. If set, Pub/Sub only delivers the messages that
match the filter. The expression must be a non\-empty string in the Pub/Sub
filtering language (https://cloud.google.com/pubsub/docs/filtering).

.TP 2m
\fB\-\-message\-retention\-duration\fR=\fIMESSAGE_RETENTION_DURATION\fR

How long to retain unacknowledged messages in the subscription's backlog, from
the moment a message is published. If \-\-retain\-acked\-messages is true, this
also configures the retention of acknowledged messages. The default value is 7
days, the minimum is 10 minutes, and the maximum is 31 days. Valid values are
strings of the form INTEGER[UNIT], where UNIT is one of "s", "m", "h", and "d"
for seconds, minutes, hours, and days, respectively. If the unit is omitted,
seconds is assumed.

.TP 2m
\fB\-\-message\-transforms\-file\fR=\fIMESSAGE_TRANSFORMS_FILE\fR

Path to YAML or JSON file containing message transforms.

.TP 2m
\fB\-\-retain\-acked\-messages\fR

Whether or not to retain acknowledged messages. If true, messages are not
expunged from the subscription's backlog until they fall out of the
\-\-message\-retention\-duration window. Acknowledged messages are not retained
by default. Use \-\-no\-retain\-acked\-messages to disable this flag.

.TP 2m

At most one of these can be specified:


.RS 2m
.TP 2m

BigQuery Config Options. The Cloud Pub/Sub service account associated with the
enclosing subscription's parent project (i.e.,
service\-{project_number}@gcp\-sa\-pubsub.iam.gserviceaccount.com) must have
permission to write to this BigQuery table.


.RS 2m
.TP 2m
\fB\-\-bigquery\-table\fR=\fIBIGQUERY_TABLE\fR

A BigQuery table of the form {project}:{dataset_name}.{table_name} to which to
write messages for this subscription.

This flag argument must be specified if any of the other arguments in this group
are specified.

.TP 2m
\fB\-\-bigquery\-service\-account\-email\fR=\fIBIGQUERY_SERVICE_ACCOUNT_EMAIL\fR

The service account email to use when writing to BigQuery. If unspecified, uses
the Pub/Sub service agent
(https://cloud.google.com/iam/docs/service\-account\-types#service\-agents).

.TP 2m
\fB\-\-drop\-unknown\-fields\fR

If either \-\-use\-topic\-schema or \-\-use\-table\-schema is set, whether or
not to ignore fields in the message that do not appear in the BigQuery table
schema. Use \-\-no\-drop\-unknown\-fields to disable this flag.

.TP 2m
\fB\-\-write\-metadata\fR

Whether or not to write message metadata including message ID, publish
timestamp, ordering key, and attributes to BigQuery. The subscription name,
message_id, and publish_time fields are put in their own columns while all other
message properties other than data (for example, an ordering_key, if present)
are written to a JSON object in the attributes column. Use
\-\-no\-write\-metadata to disable this flag.

.TP 2m

At most one of these can be specified:


.RS 2m
.TP 2m
\fB\-\-use\-table\-schema\fR

Whether or not to use the BigQuery table schema when writing messages to
BigQuery. Use \-\-no\-use\-table\-schema to disable this flag.

.TP 2m
\fB\-\-use\-topic\-schema\fR

Whether or not to use the schema for the subscription's topic (if it exists)
when writing messages to BigQuery. If \-\-drop\-unknown\-fields is not set, then
the BigQuery schema must contain all fields that are present in the topic
schema. Use \-\-no\-use\-topic\-schema to disable this flag.

.RE
.RE
.sp
.TP 2m

Cloud Storage Config Options. The Cloud Pub/Sub service account associated with
the enclosing subscription's parent project (i.e.,
service\-{project_number}@gcp\-sa\-pubsub.iam.gserviceaccount.com) must have
permission to write to this Cloud Storage bucket and to read this bucket's
metadata.


.RS 2m
.TP 2m
\fB\-\-cloud\-storage\-bucket\fR=\fICLOUD_STORAGE_BUCKET\fR

A Cloud Storage bucket to which to write messages for this subscription.

This flag argument must be specified if any of the other arguments in this group
are specified.

.TP 2m
\fB\-\-cloud\-storage\-file\-datetime\-format\fR=\fICLOUD_STORAGE_FILE_DATETIME_FORMAT\fR

The custom datetime format string for Cloud Storage filename. See the datetime
format guidance
(https://cloud.google.com/pubsub/docs/create\-cloudstorage\-subscription#file_names).

.TP 2m
\fB\-\-cloud\-storage\-file\-prefix\fR=\fICLOUD_STORAGE_FILE_PREFIX\fR

The prefix for Cloud Storage filename.

.TP 2m
\fB\-\-cloud\-storage\-file\-suffix\fR=\fICLOUD_STORAGE_FILE_SUFFIX\fR

The suffix for Cloud Storage filename.

.TP 2m
\fB\-\-cloud\-storage\-max\-bytes\fR=\fICLOUD_STORAGE_MAX_BYTES\fR

The maximum bytes that can be written to a Cloud Storage file before a new file
is created. The value must be between 1000B and 10GB. If the unit is omitted, KB
is assumed.

.TP 2m
\fB\-\-cloud\-storage\-max\-duration\fR=\fICLOUD_STORAGE_MAX_DURATION\fR

The maximum duration that can elapse before a new Cloud Storage file is created.
The value must be between 1m and 10m. Valid values are strings of the form
INTEGER[UNIT], where UNIT is one of "s", "m", "h", and "d" for seconds, minutes,
hours, and days, respectively. If the unit is omitted, seconds is assumed.

.TP 2m
\fB\-\-cloud\-storage\-max\-messages\fR=\fICLOUD_STORAGE_MAX_MESSAGES\fR

The maximum number of messages that can be written to a Cloud Storage file
before a new file is created. The value must be greater than or equal to 1000.

.TP 2m
\fB\-\-cloud\-storage\-output\-format\fR=\fIOUTPUT_FORMAT\fR; default="text"

The output format for data written to Cloud Storage. Values: text (messages will
be written as raw text, separated by a newline) or avro (messages will be
written as an Avro binary). \fIOUTPUT_FORMAT\fR must be one of: \fBtext\fR,
\fBavro\fR.

.TP 2m
\fB\-\-cloud\-storage\-service\-account\-email\fR=\fICLOUD_STORAGE_SERVICE_ACCOUNT_EMAIL\fR

The service account email to use when writing to Cloud Storage. If unspecified,
uses the Pub/Sub service agent
(https://cloud.google.com/iam/docs/service\-account\-types#service\-agents).

.TP 2m
\fB\-\-cloud\-storage\-use\-topic\-schema\fR

Whether or not to use the schema for the subscription's topic (if it exists)
when writing messages to Cloud Storage. This has an effect only for
subscriptions with \-\-cloud\-storage\-output\-format=avro. Use
\-\-no\-cloud\-storage\-use\-topic\-schema to disable this flag.

.TP 2m
\fB\-\-cloud\-storage\-write\-metadata\fR

Whether or not to write the subscription name, message_id, publish_time,
attributes, and ordering_key as additional fields in the output. The
subscription name, message_id, and publish_time fields are put in their own
fields while all other message properties other than data (for example, an
ordering_key, if present) are added as entries in the attributes map. This has
an effect only for subscriptions with \-\-cloud\-storage\-output\-format=avro.
Use \-\-no\-cloud\-storage\-write\-metadata to disable this flag.

.RE
.RE
.sp
.TP 2m

Dead Letter Queue Options. The Cloud Pub/Sub service account associated with the
enclosing subscription's parent project (i.e.,
service\-{project_number}@gcp\-sa\-pubsub.iam.gserviceaccount.com) must have
permission to Publish() to this topic and Acknowledge() messages on this
subscription.


.RS 2m
.TP 2m
\fB\-\-max\-delivery\-attempts\fR=\fIMAX_DELIVERY_ATTEMPTS\fR

Maximum number of delivery attempts for any message. The value must be between 5
and 100. Defaults to 5. \f5\-\-dead\-letter\-topic\fR must also be specified.

.TP 2m

Dead letter topic resource \- Name of the topic to publish dead letter messages
to. The arguments in this group can be used to specify the attributes of this
resource.


.RS 2m
.TP 2m
\fB\-\-dead\-letter\-topic\fR=\fIDEAD_LETTER_TOPIC\fR

ID of the dead\-letter\-topic or fully qualified identifier for the
dead\-letter\-topic.

To set the \f5topic\fR attribute:
.RS 2m
.IP "\(em" 2m
provide the argument \f5\-\-dead\-letter\-topic\fR on the command line.
.RE
.sp

This flag argument must be specified if any of the other arguments in this group
are specified.

.TP 2m
\fB\-\-dead\-letter\-topic\-project\fR=\fIDEAD_LETTER_TOPIC_PROJECT\fR

Project ID of the Google Cloud project for the dead\-letter\-topic.

To set the \f5project\fR attribute:
.RS 2m
.IP "\(em" 2m
provide the argument \f5\-\-dead\-letter\-topic\fR on the command line with a
fully specified name;
.IP "\(em" 2m
provide the argument \f5\-\-dead\-letter\-topic\-project\fR on the command line;
.IP "\(em" 2m
provide the argument \f5\-\-project\fR on the command line;
.IP "\(em" 2m
set the property \f5core/project\fR.
.RE
.sp

.RE
.RE
.sp
.TP 2m

Retry Policy Options. Retry policy specifies how Cloud Pub/Sub retries message
delivery for this subscription.


.RS 2m
.TP 2m
\fB\-\-max\-retry\-delay\fR=\fIMAX_RETRY_DELAY\fR

The maximum delay between consecutive deliveries of a given message. Value
should be between 0 and 600 seconds. Defaults to 600 seconds. Valid values are
strings of the form INTEGER[UNIT], where UNIT is one of "s", "m", "h", and "d"
for seconds, minutes, hours, and days, respectively. If the unit is omitted,
seconds is assumed.

.TP 2m
\fB\-\-min\-retry\-delay\fR=\fIMIN_RETRY_DELAY\fR

The minimum delay between consecutive deliveries of a given message. Value
should be between 0 and 600 seconds. Defaults to 10 seconds. Valid values are
strings of the form INTEGER[UNIT], where UNIT is one of "s", "m", "h", and "d"
for seconds, minutes, hours, and days, respectively. If the unit is omitted,
seconds is assumed.

.RE
.sp
.TP 2m

Push Config Options. Configuration for a push delivery endpoint.


.RS 2m
.TP 2m
\fB\-\-push\-auth\-service\-account\fR=\fISERVICE_ACCOUNT_EMAIL\fR

Service account email used as the identity for the generated Open ID Connect
token for authenticated push.

.TP 2m
\fB\-\-push\-auth\-token\-audience\fR=\fIOPTIONAL_AUDIENCE_OVERRIDE\fR

Audience used in the generated Open ID Connect token for authenticated push. If
not specified, it will be set to the push\-endpoint.

.TP 2m
\fB\-\-push\-endpoint\fR=\fIPUSH_ENDPOINT\fR

A URL to use as the endpoint for this subscription. This will also automatically
set the subscription type to PUSH.

.TP 2m

NoWrapper Config Options.


.RS 2m
.TP 2m
\fB\-\-push\-no\-wrapper\fR

When set, the message data is delivered directly as the HTTP body. Use
\-\-no\-push\-no\-wrapper to disable this flag.

This flag argument must be specified if any of the other arguments in this group
are specified.

.TP 2m
\fB\-\-push\-no\-wrapper\-write\-metadata\fR

When true, writes the Pub/Sub message metadata to
\f5x\-goog\-pubsub\-<KEY>:<VAL>\fR headers of the HTTP request. Writes the
Pub/Sub message attributes to \f5<KEY>:<VAL>\fR headers of the HTTP request. Use
\-\-no\-push\-no\-wrapper\-write\-metadata to disable this flag.


.RE
.RE
.RE
.sp

.SH "GCLOUD WIDE FLAGS"

These flags are available to all commands: \-\-access\-token\-file, \-\-account,
\-\-billing\-project, \-\-configuration, \-\-flags\-file, \-\-flatten,
\-\-format, \-\-help, \-\-impersonate\-service\-account, \-\-log\-http,
\-\-project, \-\-quiet, \-\-trace\-token, \-\-user\-output\-enabled,
\-\-verbosity.

Run \fB$ gcloud help\fR for details.



.SH "NOTES"

This command is currently in beta and might change without notice. These
variants are also available:

.RS 2m
$ gcloud pubsub subscriptions create
.RE

.RS 2m
$ gcloud alpha pubsub subscriptions create
.RE