gcloud-help/gcloud/beta/pubsub/subscriptions/create

NAME
    gcloud beta pubsub subscriptions create - creates one or more Cloud Pub/Sub
        subscriptions

SYNOPSIS
    gcloud beta pubsub subscriptions create SUBSCRIPTION [SUBSCRIPTION ...]
        (--topic=TOPIC : --topic-project=TOPIC_PROJECT)
        [--ack-deadline=ACK_DEADLINE] [--enable-exactly-once-delivery]
        [--enable-message-ordering] [--expiration-period=EXPIRATION_PERIOD]
        [--labels=[KEY=VALUE,...]] [--message-filter=MESSAGE_FILTER]
        [--message-retention-duration=MESSAGE_RETENTION_DURATION]
        [--message-transforms-file=MESSAGE_TRANSFORMS_FILE]
        [--retain-acked-messages] [--tags=[KEY=VALUE,...]]
        [[--bigquery-table=BIGQUERY_TABLE
          : --bigquery-service-account-email=BIGQUERY_SERVICE_ACCOUNT_EMAIL
          --drop-unknown-fields --write-metadata --use-table-schema
          | --use-topic-schema] | [--bigtable-table=BIGTABLE_TABLE
          : --bigtable-app-profile-id=BIGTABLE_APP_PROFILE_ID
          --bigtable-service-account-email=BIGTABLE_SERVICE_ACCOUNT_EMAIL
          --bigtable-write-metadata]
          | [--cloud-storage-bucket=CLOUD_STORAGE_BUCKET
          : --cloud-storage-file-datetime-format=CLOUD_STORAGE_FILE_DATETIME_FORMAT --cloud-storage-file-prefix=CLOUD_STORAGE_FILE_PREFIX --cloud-storage-file-suffix=CLOUD_STORAGE_FILE_SUFFIX --cloud-storage-max-bytes=CLOUD_STORAGE_MAX_BYTES --cloud-storage-max-duration=CLOUD_STORAGE_MAX_DURATION --cloud-storage-max-messages=CLOUD_STORAGE_MAX_MESSAGES --cloud-storage-output-format=OUTPUT_FORMAT; default="text" --cloud-storage-service-account-email=CLOUD_STORAGE_SERVICE_ACCOUNT_EMAIL --cloud-storage-use-topic-schema --cloud-storage-write-metadata]]
        [--max-delivery-attempts=MAX_DELIVERY_ATTEMPTS
          [--dead-letter-topic=DEAD_LETTER_TOPIC
          : --dead-letter-topic-project=DEAD_LETTER_TOPIC_PROJECT]]
        [--max-retry-delay=MAX_RETRY_DELAY --min-retry-delay=MIN_RETRY_DELAY]
        [--push-auth-service-account=SERVICE_ACCOUNT_EMAIL
          --push-auth-token-audience=OPTIONAL_AUDIENCE_OVERRIDE
          --push-endpoint=PUSH_ENDPOINT [--push-no-wrapper
          : --push-no-wrapper-write-metadata]] [GCLOUD_WIDE_FLAG ...]

DESCRIPTION
    (BETA) 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.

POSITIONAL ARGUMENTS
     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 project attribute:
      ◆ provide the argument subscription on the command line with a fully
        specified name;
      ◆ provide the argument --project on the command line;
      ◆ set the property core/project.

     This must be specified.

       SUBSCRIPTION [SUBSCRIPTION ...]
          IDs of the subscriptions or fully qualified identifiers for the
          subscriptions.

          To set the subscription attribute:
          ▸ provide the argument subscription on the command line.

REQUIRED FLAGS
     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.

       --topic=TOPIC
          ID of the topic or fully qualified identifier for the topic.

          To set the topic attribute:
          ▸ provide the argument --topic on the command line.

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

       --topic-project=TOPIC_PROJECT
          Project ID of the Google Cloud project for the topic.

          To set the project attribute:
          ▸ provide the argument --topic on the command line with a fully
            specified name;
          ▸ provide the argument --topic-project on the command line;
          ▸ provide the argument --project on the command line;
          ▸ set the property core/project.

OPTIONAL FLAGS
     --ack-deadline=ACK_DEADLINE
        The number of seconds the system will wait for a subscriber to
        acknowledge receiving a message before re-attempting delivery.

     --enable-exactly-once-delivery
        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 message_id 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.

     --enable-message-ordering
        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.

     --expiration-period=EXPIRATION_PERIOD
        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.

     --labels=[KEY=VALUE,...]
        List of label KEY=VALUE pairs to add.

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

     --message-filter=MESSAGE_FILTER
        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).

     --message-retention-duration=MESSAGE_RETENTION_DURATION
        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.

     --message-transforms-file=MESSAGE_TRANSFORMS_FILE
        Path to YAML or JSON file containing message transforms.

     --retain-acked-messages
        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.

     --tags=[KEY=VALUE,...]
        List of tags KEY=VALUE pairs to bind. Each item must be expressed as
        <tag-key-namespaced-name>=<tag-value-short-name>. Example:
        123/environment=production,123/costCenter=marketing

     At most one of these can be specified:

       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.

       --bigquery-table=BIGQUERY_TABLE
          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.

       --bigquery-service-account-email=BIGQUERY_SERVICE_ACCOUNT_EMAIL
          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).

       --drop-unknown-fields
          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.

       --write-metadata
          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.

       At most one of these can be specified:

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

         --use-topic-schema
            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.

       Bigtable 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 Bigtable table.

       --bigtable-table=BIGTABLE_TABLE
          A Bigtable table of the form
          projects/{project}/instances/{instance_name}/tables/{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.

       --bigtable-app-profile-id=BIGTABLE_APP_PROFILE_ID
          The app profile to use for the Bigtable writes.

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

       --bigtable-write-metadata
          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.

       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.

       --cloud-storage-bucket=CLOUD_STORAGE_BUCKET
          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.

       --cloud-storage-file-datetime-format=CLOUD_STORAGE_FILE_DATETIME_FORMAT
          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).

       --cloud-storage-file-prefix=CLOUD_STORAGE_FILE_PREFIX
          The prefix for Cloud Storage filename.

       --cloud-storage-file-suffix=CLOUD_STORAGE_FILE_SUFFIX
          The suffix for Cloud Storage filename.

       --cloud-storage-max-bytes=CLOUD_STORAGE_MAX_BYTES
          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.

       --cloud-storage-max-duration=CLOUD_STORAGE_MAX_DURATION
          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.

       --cloud-storage-max-messages=CLOUD_STORAGE_MAX_MESSAGES
          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.

       --cloud-storage-output-format=OUTPUT_FORMAT; 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). OUTPUT_FORMAT must
          be one of: text, avro.

       --cloud-storage-service-account-email=CLOUD_STORAGE_SERVICE_ACCOUNT_EMAIL
          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).

       --cloud-storage-use-topic-schema
          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.

       --cloud-storage-write-metadata
          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.

     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.

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

     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.

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

        To set the topic attribute:
        ◆ provide the argument --dead-letter-topic on the command line.

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

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

        To set the project attribute:
        ◆ provide the argument --dead-letter-topic on the command line with a
          fully specified name;
        ◆ provide the argument --dead-letter-topic-project on the command
          line;
        ◆ provide the argument --project on the command line;
        ◆ set the property core/project.

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

     --max-retry-delay=MAX_RETRY_DELAY
        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.

     --min-retry-delay=MIN_RETRY_DELAY
        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.

     Push Config Options. Configuration for a push delivery endpoint.

     --push-auth-service-account=SERVICE_ACCOUNT_EMAIL
        Service account email used as the identity for the generated Open ID
        Connect token for authenticated push.

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

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

     NoWrapper Config Options.

     --push-no-wrapper
        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.

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

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 $ gcloud help for details.

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

        $ gcloud pubsub subscriptions create

        $ gcloud alpha pubsub subscriptions create