gcloud-help/gcloud/pubsub/subscriptions/create

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

SYNOPSIS
    gcloud 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]
        [--retain-acked-messages]
        [[--bigquery-table=BIGQUERY_TABLE
          : --bigquery-service-account-email=BIGQUERY_SERVICE_ACCOUNT_EMAIL
          --drop-unknown-fields --write-metadata --use-table-schema
          | --use-topic-schema] | [--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
    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.

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

     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.

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

       --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
    These variants are also available:

        $ gcloud alpha pubsub subscriptions create

        $ gcloud beta pubsub subscriptions create