gcp_cloudscheduler_job – Creates a GCP Job¶
New in version 2.9.
Synopsis¶
- A scheduled job that can publish a pubsub message or a http request every X interval of time, using crontab format string.
- To use Cloud Scheduler your project must contain an App Engine app that is located in one of the supported regions. If your project does not have an App Engine app, you must create one.
Requirements¶
The below requirements are needed on the host that executes this module.
- python >= 2.6
- requests >= 2.18.4
- google-auth >= 1.3.0
Parameters¶
| Parameter | Choices/Defaults | Comments | ||
|---|---|---|---|---|
| app_engine_http_target 
                    dictionary
                                                                 | App Engine HTTP target. If the job providers a App Engine HTTP target the cron will send a request to the service instance . | |||
| app_engine_routing 
                    dictionary
                                                                 | App Engine Routing setting for the job. | |||
| instance 
                    string
                                                                 | App instance. By default, the job is sent to an instance which is available when the job is attempted. | |||
| service 
                    string
                                                                 | App service. By default, the job is sent to the service which is the default service when the job is attempted. | |||
| version 
                    string
                                                                 | App version. By default, the job is sent to the version which is the default version when the job is attempted. | |||
| body 
                    string
                                                                 | HTTP request body. A request body is allowed only if the HTTP method is POST or PUT. It will result in invalid argument error to set a body on a job with an incompatible HttpMethod. | |||
| headers 
                    dictionary
                                                                 | HTTP request headers. This map contains the header field names and values. Headers can be set when the job is created. | |||
| http_method 
                    string
                                                                 | Which HTTP method to use for the request. | |||
| relative_uri 
                    string
                                             / required                     | The relative URI. | |||
| auth_kind 
                    string
                                             / required                     | 
 | The type of credential used. | ||
| description 
                    string
                                                                 | A human-readable description for the job. This string must not contain more than 500 characters. | |||
| env_type 
                    string
                                                                 | Specifies which Ansible environment you're running this module within. This should not be set unless you know what you're doing. This only alters the User Agent string for any API requests. | |||
| http_target 
                    dictionary
                                                                 | HTTP target. If the job providers a http_target the cron will send a request to the targeted url . | |||
| body 
                    string
                                                                 | HTTP request body. A request body is allowed only if the HTTP method is POST, PUT, or PATCH. It is an error to set body on a job with an incompatible HttpMethod. | |||
| headers 
                    dictionary
                                                                 | This map contains the header field names and values. Repeated headers are not supported, but a header value can contain commas. | |||
| http_method 
                    string
                                                                 | Which HTTP method to use for the request. | |||
| oauth_token 
                    dictionary
                                                                 | Contains information needed for generating an OAuth token. This type of authorization should be used when sending requests to a GCP endpoint. | |||
| scope 
                    string
                                                                 | OAuth scope to be used for generating OAuth access token. If not specified, "https://www.googleapis.com/auth/cloud-platform" will be used. | |||
| service_account_email 
                    string
                                                                 | Service account email to be used for generating OAuth token. The service account must be within the same project as the job. | |||
| oidc_token 
                    dictionary
                                                                 | Contains information needed for generating an OpenID Connect token. This type of authorization should be used when sending requests to third party endpoints or Cloud Run. | |||
| audience 
                    string
                                                                 | Audience to be used when generating OIDC token. If not specified, the URI specified in target will be used. | |||
| service_account_email 
                    string
                                                                 | Service account email to be used for generating OAuth token. The service account must be within the same project as the job. | |||
| uri 
                    string
                                             / required                     | The full URI path that the request will be sent to. | |||
| name 
                    string
                                             / required                     | The name of the job. | |||
| project 
                    string
                                                                 | The Google Cloud Platform project to use. | |||
| pubsub_target 
                    dictionary
                                                                 | Pub/Sub target If the job providers a Pub/Sub target the cron will publish a message to the provided topic . | |||
| attributes 
                    dictionary
                                                                 | Attributes for PubsubMessage. Pubsub message must contain either non-empty data, or at least one attribute. | |||
| data 
                    string
                                                                 | The message payload for PubsubMessage. Pubsub message must contain either non-empty data, or at least one attribute. | |||
| topic_name 
                    string
                                             / required                     | The name of the Cloud Pub/Sub topic to which messages will be published when a job is delivered. The topic name must be in the same format as required by PubSub's PublishRequest.name, for example projects/PROJECT_ID/topics/TOPIC_ID. | |||
| region 
                    string
                                             / required                     | Region where the scheduler job resides . | |||
| retry_config 
                    dictionary
                                                                 | By default, if a job does not complete successfully, meaning that an acknowledgement is not received from the handler, then it will be retried with exponential backoff according to the settings . | |||
| max_backoff_duration 
                    string
                                                                 | The maximum amount of time to wait before retrying a job after it fails. A duration in seconds with up to nine fractional digits, terminated by 's'. | |||
| max_doublings 
                    integer
                                                                 | The time between retries will double maxDoublings times. A job's retry interval starts at minBackoffDuration, then doubles maxDoublings times, then increases linearly, and finally retries retries at intervals of maxBackoffDuration up to retryCount times. | |||
| max_retry_duration 
                    string
                                                                 | The time limit for retrying a failed job, measured from time when an execution was first attempted. If specified with retryCount, the job will be retried until both limits are reached. A duration in seconds with up to nine fractional digits, terminated by 's'. | |||
| min_backoff_duration 
                    string
                                                                 | The minimum amount of time to wait before retrying a job after it fails. A duration in seconds with up to nine fractional digits, terminated by 's'. | |||
| retry_count 
                    integer
                                                                 | The number of attempts that the system will make to run a job using the exponential backoff procedure described by maxDoublings. Values greater than 5 and negative values are not allowed. | |||
| schedule 
                    string
                                                                 | Describes the schedule on which the job will be executed. | |||
| scopes 
                    list
                                                                 | Array of scopes to be used. | |||
| service_account_contents 
                    jsonarg
                                                                 | The contents of a Service Account JSON file, either in a dictionary or as a JSON string that represents it. | |||
| service_account_email 
                    string
                                                                 | An optional service account email address if machineaccount is selected and the user does not wish to use the default email. | |||
| service_account_file 
                    path
                                                                 | The path of a Service Account JSON file if serviceaccount is selected as type. | |||
| state 
                    string
                                                                 | 
 | Whether the given object should exist in GCP | ||
| time_zone 
                    string
                                                                 | Default: "Etc/UTC" | Specifies the time zone to be used in interpreting schedule. The value of this field must be a time zone name from the tz database. | ||
Notes¶
Note
- API Reference: https://cloud.google.com/scheduler/docs/reference/rest/
- Official Documentation: https://cloud.google.com/scheduler/
- for authentication, you can set service_account_file using the c(gcp_service_account_file) env variable.
- for authentication, you can set service_account_contents using the c(GCP_SERVICE_ACCOUNT_CONTENTS) env variable.
- For authentication, you can set service_account_email using the GCP_SERVICE_ACCOUNT_EMAILenv variable.
- For authentication, you can set auth_kind using the GCP_AUTH_KINDenv variable.
- For authentication, you can set scopes using the GCP_SCOPESenv variable.
- Environment variables values will only be used if the playbook values are not set.
- The service_account_email and service_account_file options are mutually exclusive.
Examples¶
- name: create a job
  gcp_cloudscheduler_job:
    name: job
    region: us-central1
    schedule: "*/4 * * * *"
    description: test app engine job
    time_zone: Europe/London
    app_engine_http_target:
      http_method: POST
      app_engine_routing:
        service: web
        version: prod
        instance: my-instance-001
      relative_uri: "/ping"
    project: test_project
    auth_kind: serviceaccount
    service_account_file: "/tmp/auth.pem"
    state: present
Return Values¶
Common return values are documented here, the following are the fields unique to this module:
| Key | Returned | Description | ||
|---|---|---|---|---|
| appEngineHttpTarget 
                  complex
                                       | success | App Engine HTTP target. If the job providers a App Engine HTTP target the cron will send a request to the service instance . | ||
| appEngineRouting 
                  complex
                                       | success | App Engine Routing setting for the job. | ||
| instance 
                  string
                                       | success | App instance. By default, the job is sent to an instance which is available when the job is attempted. | ||
| service 
                  string
                                       | success | App service. By default, the job is sent to the service which is the default service when the job is attempted. | ||
| version 
                  string
                                       | success | App version. By default, the job is sent to the version which is the default version when the job is attempted. | ||
| body 
                  string
                                       | success | HTTP request body. A request body is allowed only if the HTTP method is POST or PUT. It will result in invalid argument error to set a body on a job with an incompatible HttpMethod. | ||
| headers 
                  dictionary
                                       | success | HTTP request headers. This map contains the header field names and values. Headers can be set when the job is created. | ||
| httpMethod 
                  string
                                       | success | Which HTTP method to use for the request. | ||
| relativeUri 
                  string
                                       | success | The relative URI. | ||
| description 
                  string
                                       | success | A human-readable description for the job. This string must not contain more than 500 characters. | ||
| httpTarget 
                  complex
                                       | success | HTTP target. If the job providers a http_target the cron will send a request to the targeted url . | ||
| body 
                  string
                                       | success | HTTP request body. A request body is allowed only if the HTTP method is POST, PUT, or PATCH. It is an error to set body on a job with an incompatible HttpMethod. | ||
| headers 
                  dictionary
                                       | success | This map contains the header field names and values. Repeated headers are not supported, but a header value can contain commas. | ||
| httpMethod 
                  string
                                       | success | Which HTTP method to use for the request. | ||
| oauthToken 
                  complex
                                       | success | Contains information needed for generating an OAuth token. This type of authorization should be used when sending requests to a GCP endpoint. | ||
| scope 
                  string
                                       | success | OAuth scope to be used for generating OAuth access token. If not specified, "https://www.googleapis.com/auth/cloud-platform" will be used. | ||
| serviceAccountEmail 
                  string
                                       | success | Service account email to be used for generating OAuth token. The service account must be within the same project as the job. | ||
| oidcToken 
                  complex
                                       | success | Contains information needed for generating an OpenID Connect token. This type of authorization should be used when sending requests to third party endpoints or Cloud Run. | ||
| audience 
                  string
                                       | success | Audience to be used when generating OIDC token. If not specified, the URI specified in target will be used. | ||
| serviceAccountEmail 
                  string
                                       | success | Service account email to be used for generating OAuth token. The service account must be within the same project as the job. | ||
| uri 
                  string
                                       | success | The full URI path that the request will be sent to. | ||
| name 
                  string
                                       | success | The name of the job. | ||
| pubsubTarget 
                  complex
                                       | success | Pub/Sub target If the job providers a Pub/Sub target the cron will publish a message to the provided topic . | ||
| attributes 
                  dictionary
                                       | success | Attributes for PubsubMessage. Pubsub message must contain either non-empty data, or at least one attribute. | ||
| data 
                  string
                                       | success | The message payload for PubsubMessage. Pubsub message must contain either non-empty data, or at least one attribute. | ||
| topicName 
                  string
                                       | success | The name of the Cloud Pub/Sub topic to which messages will be published when a job is delivered. The topic name must be in the same format as required by PubSub's PublishRequest.name, for example projects/PROJECT_ID/topics/TOPIC_ID. | ||
| region 
                  string
                                       | success | Region where the scheduler job resides . | ||
| retryConfig 
                  complex
                                       | success | By default, if a job does not complete successfully, meaning that an acknowledgement is not received from the handler, then it will be retried with exponential backoff according to the settings . | ||
| maxBackoffDuration 
                  string
                                       | success | The maximum amount of time to wait before retrying a job after it fails. A duration in seconds with up to nine fractional digits, terminated by 's'. | ||
| maxDoublings 
                  integer
                                       | success | The time between retries will double maxDoublings times. A job's retry interval starts at minBackoffDuration, then doubles maxDoublings times, then increases linearly, and finally retries retries at intervals of maxBackoffDuration up to retryCount times. | ||
| maxRetryDuration 
                  string
                                       | success | The time limit for retrying a failed job, measured from time when an execution was first attempted. If specified with retryCount, the job will be retried until both limits are reached. A duration in seconds with up to nine fractional digits, terminated by 's'. | ||
| minBackoffDuration 
                  string
                                       | success | The minimum amount of time to wait before retrying a job after it fails. A duration in seconds with up to nine fractional digits, terminated by 's'. | ||
| retryCount 
                  integer
                                       | success | The number of attempts that the system will make to run a job using the exponential backoff procedure described by maxDoublings. Values greater than 5 and negative values are not allowed. | ||
| schedule 
                  string
                                       | success | Describes the schedule on which the job will be executed. | ||
| timeZone 
                  string
                                       | success | Specifies the time zone to be used in interpreting schedule. The value of this field must be a time zone name from the tz database. | ||
Status¶
- This module is not guaranteed to have a backwards compatible interface. [preview]
- This module is maintained by the Ansible Community. [community]
Authors¶
- Google Inc. (@googlecloudplatform)
Hint
If you notice any issues in this documentation, you can edit this document to improve it.
