google.cloud.gcp_cloudscheduler_job module – Creates a GCP Job

Note

This module is part of the google.cloud collection (version 1.4.1).

You might already have this collection installed if you are using the ansible package. It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install google.cloud. You need further requirements to be able to use this module, see Requirements for details.

To use it in a playbook, specify: google.cloud.gcp_cloudscheduler_job.

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

Comments

access_token

string

An OAuth2 access token if credential type is accesstoken.

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.

A base64-encoded string.

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.

attempt_deadline

string

The deadline for job attempts. If the request handler does not respond by this deadline then the request is cancelled and the attempt is marked as a DEADLINE_EXCEEDED failure. The failed attempt can be viewed in execution logs. Cloud Scheduler will retry the job according to the RetryConfig.

The allowed duration for this deadline is: * For HTTP targets, between 15 seconds and 30 minutes.

* For App Engine HTTP targets, between 15 seconds and 24 hours.

* **Note**: For PubSub targets, this field is ignored - setting it will introduce an unresolvable diff.

A duration in seconds with up to nine fractional digits, terminated by ‘s’. Example: “3.5s” .

Default: "180s"

auth_kind

string / required

The type of credential used.

Choices:

  • "application"

  • "machineaccount"

  • "serviceaccount"

  • "accesstoken"

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.

A base64-encoded string.

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 / required

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 / required

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.

A base64-encoded string.

topic_name

string / required

The full resource name for the Cloud Pub/Sub topic to which messages will be published when a job is delivered. ~>**NOTE:** The topic name must be in the same format as required by PubSub’s PublishRequest.name, e.g. `projects/my-project/topics/my-topic`.

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 / elements=string

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

Choices:

  • "present" ← (default)

  • "absent"

time_zone

string

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.

Default: "Etc/UTC"

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 GCP_SERVICE_ACCOUNT_FILE env variable.

  • for authentication, you can set service_account_contents using the GCP_SERVICE_ACCOUNT_CONTENTS env variable.

  • For authentication, you can set service_account_email using the GCP_SERVICE_ACCOUNT_EMAIL env variable.

  • For authentication, you can set access_token using the GCP_ACCESS_TOKEN env variable.

  • For authentication, you can set auth_kind using the GCP_AUTH_KIND env variable.

  • For authentication, you can set scopes using the GCP_SCOPES env 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
  google.cloud.gcp_cloudscheduler_job:
    name: job
    region: us-central1
    schedule: "*/4 * * * *"
    description: test app engine job
    time_zone: Europe/London
    attempt_deadline: 320s
    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

Description

appEngineHttpTarget

complex

App Engine HTTP target.

If the job providers a App Engine HTTP target the cron will send a request to the service instance .

Returned: success

appEngineRouting

complex

App Engine Routing setting for the job.

Returned: success

instance

string

App instance.

By default, the job is sent to an instance which is available when the job is attempted.

Returned: success

service

string

App service.

By default, the job is sent to the service which is the default service when the job is attempted.

Returned: success

version

string

App version.

By default, the job is sent to the version which is the default version when the job is attempted.

Returned: success

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.

A base64-encoded string.

Returned: success

headers

dictionary

HTTP request headers.

This map contains the header field names and values. Headers can be set when the job is created.

Returned: success

httpMethod

string

Which HTTP method to use for the request.

Returned: success

relativeUri

string

The relative URI.

Returned: success

attemptDeadline

string

The deadline for job attempts. If the request handler does not respond by this deadline then the request is cancelled and the attempt is marked as a DEADLINE_EXCEEDED failure. The failed attempt can be viewed in execution logs. Cloud Scheduler will retry the job according to the RetryConfig.

The allowed duration for this deadline is: * For HTTP targets, between 15 seconds and 30 minutes.

* For App Engine HTTP targets, between 15 seconds and 24 hours.

* **Note**: For PubSub targets, this field is ignored - setting it will introduce an unresolvable diff.

A duration in seconds with up to nine fractional digits, terminated by ‘s’. Example: “3.5s” .

Returned: success

description

string

A human-readable description for the job. This string must not contain more than 500 characters.

Returned: success

httpTarget

complex

HTTP target.

If the job providers a http_target the cron will send a request to the targeted url .

Returned: success

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.

A base64-encoded string.

Returned: success

headers

dictionary

This map contains the header field names and values. Repeated headers are not supported, but a header value can contain commas.

Returned: success

httpMethod

string

Which HTTP method to use for the request.

Returned: success

oauthToken

complex

Contains information needed for generating an OAuth token.

This type of authorization should be used when sending requests to a GCP endpoint.

Returned: success

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.

Returned: success

serviceAccountEmail

string

Service account email to be used for generating OAuth token.

The service account must be within the same project as the job.

Returned: success

oidcToken

complex

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.

Returned: success

audience

string

Audience to be used when generating OIDC token. If not specified, the URI specified in target will be used.

Returned: success

serviceAccountEmail

string

Service account email to be used for generating OAuth token.

The service account must be within the same project as the job.

Returned: success

uri

string

The full URI path that the request will be sent to.

Returned: success

name

string

The name of the job.

Returned: success

pubsubTarget

complex

Pub/Sub target If the job providers a Pub/Sub target the cron will publish a message to the provided topic .

Returned: success

attributes

dictionary

Attributes for PubsubMessage.

Pubsub message must contain either non-empty data, or at least one attribute.

Returned: success

data

string

The message payload for PubsubMessage.

Pubsub message must contain either non-empty data, or at least one attribute.

A base64-encoded string.

Returned: success

topicName

string

The full resource name for the Cloud Pub/Sub topic to which messages will be published when a job is delivered. ~>**NOTE:** The topic name must be in the same format as required by PubSub’s PublishRequest.name, e.g. `projects/my-project/topics/my-topic`.

Returned: success

region

string

Region where the scheduler job resides .

Returned: success

retryConfig

complex

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 .

Returned: success

maxBackoffDuration

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

Returned: success

maxDoublings

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.

Returned: success

maxRetryDuration

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

Returned: success

minBackoffDuration

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

Returned: success

retryCount

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.

Returned: success

schedule

string

Describes the schedule on which the job will be executed.

Returned: success

timeZone

string

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.

Returned: success

Authors

  • Google Inc. (@googlecloudplatform)