oracle.oci.oci_resource_manager_job – Manage a Job resource in Oracle Cloud Infrastructure

Note

This plugin is part of the oracle.oci collection (version 5.3.0).

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

To use it in a playbook, specify: oracle.oci.oci_resource_manager_job.

New in version 2.9.0: of oracle.oci

Synopsis

  • This module allows the user to create, update and delete a Job resource in Oracle Cloud Infrastructure

  • For state=present, creates a job.

Requirements

The below requirements are needed on the host that executes this module.

Parameters

Parameter Choices/Defaults Comments
api_user
string
The OCID of the user, on whose behalf, OCI APIs are invoked. If not set, then the value of the OCI_USER_ID environment variable, if any, is used. This option is required if the user is not specified through a configuration file (See config_file_location). To get the user's OCID, please refer https://docs.us-phoenix-1.oraclecloud.com/Content/API/Concepts/apisigningkey.htm.
api_user_fingerprint
string
Fingerprint for the key pair being used. If not set, then the value of the OCI_USER_FINGERPRINT environment variable, if any, is used. This option is required if the key fingerprint is not specified through a configuration file (See config_file_location). To get the key pair's fingerprint value please refer https://docs.us-phoenix-1.oraclecloud.com/Content/API/Concepts/apisigningkey.htm.
api_user_key_file
string
Full path and filename of the private key (in PEM format). If not set, then the value of the OCI_USER_KEY_FILE variable, if any, is used. This option is required if the private key is not specified through a configuration file (See config_file_location). If the key is encrypted with a pass-phrase, the api_user_key_pass_phrase option must also be provided.
api_user_key_pass_phrase
string
Passphrase used by the key referenced in api_user_key_file, if it is encrypted. If not set, then the value of the OCI_USER_KEY_PASS_PHRASE variable, if any, is used. This option is required if the key passphrase is not specified through a configuration file (See config_file_location).
apply_job_plan_resolution
dictionary
is_auto_approved
boolean
    Choices:
  • no
  • yes
Specifies whether to use the configuration directly, without reference to a Plan job. `True` if using the configuration directly. Note that it is not necessary for a Plan job to have run successfully.
is_use_latest_job_id
boolean
    Choices:
  • no
  • yes
Specifies whether to use the OCID of the most recently run plan job. `True` if using the latest job OCID. Must be a plan job that completed successfully.
plan_job_id
string
The OCID that specifies the most recently executed plan job.
auth_purpose
string
    Choices:
  • service_principal
The auth purpose which can be used in conjunction with 'auth_type=instance_principal'. The default auth_purpose for instance_principal is None.
auth_type
string
    Choices:
  • api_key ←
  • instance_principal
  • instance_obo_user
  • resource_principal
  • security_token
The type of authentication to use for making API requests. By default auth_type="api_key" based authentication is performed and the API key (see api_user_key_file) in your config file will be used. If this 'auth_type' module option is not specified, the value of the OCI_ANSIBLE_AUTH_TYPE, if any, is used. Use auth_type="instance_principal" to use instance principal based authentication when running ansible playbooks within an OCI compute instance.
cert_bundle
string
The full path to a CA certificate bundle to be used for SSL verification. This will override the default CA certificate bundle. If not set, then the value of the OCI_ANSIBLE_CERT_BUNDLE variable, if any, is used.
config_file_location
string
Path to configuration file. If not set then the value of the OCI_CONFIG_FILE environment variable, if any, is used. Otherwise, defaults to ~/.oci/config.
config_profile_name
string
The profile to load from the config file referenced by config_file_location. If not set, then the value of the OCI_CONFIG_PROFILE environment variable, if any, is used. Otherwise, defaults to the "DEFAULT" profile in config_file_location.
defined_tags
dictionary
Defined tags for this resource. Each key is predefined and scoped to a namespace. For more information, see Resource Tags. Example: `{"Operations": {"CostCenter": "42"}}`
This parameter is updatable.
display_name
string
Description of the job.
Required for create, update, delete when environment variable OCI_USE_NAME_AS_IDENTIFIER is set.
This parameter is updatable when OCI_USE_NAME_AS_IDENTIFIER is not set.

aliases: name
force_create
boolean
    Choices:
  • no ←
  • yes
Whether to attempt non-idempotent creation of a resource. By default, create resource is an idempotent operation, and doesn't create the resource if it already exists. Setting this option to true, forcefully creates a copy of the resource, even if it already exists.This option is mutually exclusive with key_by.
freeform_tags
dictionary
Free-form tags associated with this resource. Each tag is a key-value pair with no predefined name, type, or namespace. For more information, see Resource Tags. Example: `{"Department": "Finance"}`
This parameter is updatable.
is_forced
boolean
    Choices:
  • no
  • yes
Indicates whether a forced cancellation is requested for the job while it was running. A forced cancellation can result in an incorrect state file. For example, the state file might not reflect the exact state of the provisioned resources.
job_id
string
The OCID of the job.
Required for update using state=present when environment variable OCI_USE_NAME_AS_IDENTIFIER is not set.
Required for delete using state=absent when environment variable OCI_USE_NAME_AS_IDENTIFIER is not set.

aliases: id
job_operation_details
dictionary
execution_plan_job_id
string
The OCID of a plan job, for use when specifying `FROM_PLAN_JOB_ID` as the `executionPlanStrategy`.
Applicable when operation is 'APPLY'
execution_plan_rollback_job_id
string
The OCID of a plan rollback job, for use when specifying `"FROM_PLAN_ROLLBACK_JOB_ID"` as the `executionPlanRollbackStrategy`.
Applicable when operation is 'APPLY_ROLLBACK'
execution_plan_rollback_strategy
string
Specifies the source of the execution plan for rollback to apply. Use `AUTO_APPROVED` to run the job without an execution plan for rollback job.
Required when operation is 'APPLY_ROLLBACK'
execution_plan_strategy
string
Specifies the source of the execution plan to apply. Use `AUTO_APPROVED` to run the job without an execution plan.
Applicable when operation is 'APPLY'
Required when operation is 'DESTROY'
is_provider_upgrade_required
boolean
    Choices:
  • no
  • yes
Specifies whether or not to upgrade provider versions. Within the version constraints of your Terraform configuration, use the latest versions available from the source of Terraform providers. For more information about this option, see L(Dependency Lock File (terraform.io),https://www.terraform.io/language/files/dependency- lock).
operation
string / required
    Choices:
  • IMPORT_TF_STATE
  • PLAN_ROLLBACK
  • APPLY_ROLLBACK
  • APPLY
  • PLAN
  • DESTROY
Terraform-specific operation to execute.
target_rollback_job_id
string
The OCID of a successful apply job to use for the plan rollback job.
Applicable when operation is 'APPLY_ROLLBACK'
Required when operation is 'PLAN_ROLLBACK'
terraform_advanced_options
dictionary
Applicable when operation is one of ['DESTROY', 'APPLY_ROLLBACK', 'APPLY', 'PLAN_ROLLBACK', 'PLAN']
detailed_log_level
string
    Choices:
  • ERROR
  • WARN
  • INFO
  • DEBUG
  • TRACE
Enables detailed logs at the specified verbosity for running the job (operation).
Applicable when operation is 'PLAN_ROLLBACK'
is_refresh_required
boolean
    Choices:
  • no
  • yes
Specifies whether to refresh the state for each resource before running the job (operation). Refreshing the state can affect performance. Consider setting to `false` if the configuration includes several resources. Used with the following operations: `PLAN`, `APPLY`, `DESTROY`.
Applicable when operation is 'PLAN_ROLLBACK'
parallelism
integer
Limits the number of concurrent Terraform operations when walking the graph. Use this parameter to help debug Terraform issues or to accomplish certain special use cases. A higher value might cause resources to be throttled. Used with the following operations: `PLAN`, `APPLY`, `DESTROY`.
Applicable when operation is 'PLAN_ROLLBACK'
tf_state_base64_encoded
string
Base64-encoded state file
Required when operation is 'IMPORT_TF_STATE'
key_by
list / elements=string
The list of attributes of this resource which should be used to uniquely identify an instance of the resource. By default, all the attributes of a resource are used to uniquely identify a resource.
operation
string
Terraform-specific operation to execute.
realm_specific_endpoint_template_enabled
boolean
    Choices:
  • no
  • yes
Enable/Disable realm specific endpoint template for service client. By Default, realm specific endpoint template is disabled. If not set, then the value of the OCI_REALM_SPECIFIC_SERVICE_ENDPOINT_TEMPLATE_ENABLED variable, if any, is used.
region
string
The Oracle Cloud Infrastructure region to use for all OCI API requests. If not set, then the value of the OCI_REGION variable, if any, is used. This option is required if the region is not specified through a configuration file (See config_file_location). Please refer to https://docs.us-phoenix-1.oraclecloud.com/Content/General/Concepts/regions.htm for more information on OCI regions.
stack_id
string
The OCID of the stack that is associated with the current job.
Required for create using state=present.
state
string
    Choices:
  • present ←
  • absent
The state of the Job.
Use state=present to create or update a Job.
Use state=absent to delete a Job.
tenancy
string
OCID of your tenancy. If not set, then the value of the OCI_TENANCY variable, if any, is used. This option is required if the tenancy OCID is not specified through a configuration file (See config_file_location). To get the tenancy OCID, please refer https://docs.us-phoenix-1.oraclecloud.com/Content/API/Concepts/apisigningkey.htm
wait
boolean
    Choices:
  • no
  • yes ←
Whether to wait for create or delete operation to complete.
wait_timeout
integer
Time, in seconds, to wait when wait=yes. Defaults to 1200 for most of the services but some services might have a longer wait timeout.

Examples

- name: Create job
  oci_resource_manager_job:
    # required
    stack_id: "ocid1.stack.oc1..xxxxxxEXAMPLExxxxxx"

    # optional
    operation: operation_example
    job_operation_details:
      # required
      tf_state_base64_encoded: tf_state_base64_encoded_example
      operation: IMPORT_TF_STATE

      # optional
      is_provider_upgrade_required: true
    apply_job_plan_resolution:
      # optional
      plan_job_id: "ocid1.planjob.oc1..xxxxxxEXAMPLExxxxxx"
      is_use_latest_job_id: true
      is_auto_approved: true
    display_name: display_name_example
    freeform_tags: {'Department': 'Finance'}
    defined_tags: {'Operations': {'CostCenter': 'US'}}

- name: Update job
  oci_resource_manager_job:
    # required
    job_id: "ocid1.job.oc1..xxxxxxEXAMPLExxxxxx"

    # optional
    display_name: display_name_example
    freeform_tags: {'Department': 'Finance'}
    defined_tags: {'Operations': {'CostCenter': 'US'}}

- name: Update job using name (when environment variable OCI_USE_NAME_AS_IDENTIFIER is set)
  oci_resource_manager_job:
    # required
    display_name: display_name_example

    # optional
    freeform_tags: {'Department': 'Finance'}
    defined_tags: {'Operations': {'CostCenter': 'US'}}

- name: Delete job
  oci_resource_manager_job:
    # required
    job_id: "ocid1.job.oc1..xxxxxxEXAMPLExxxxxx"
    state: absent

    # optional
    is_forced: true

- name: Delete job using name (when environment variable OCI_USE_NAME_AS_IDENTIFIER is set)
  oci_resource_manager_job:
    # required
    display_name: display_name_example
    state: absent

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key Returned Description
job
complex
on success
Details of the Job resource acted upon by the current operation

Sample:
{'apply_job_plan_resolution': {'is_auto_approved': True, 'is_use_latest_job_id': True, 'plan_job_id': 'ocid1.planjob.oc1..xxxxxxEXAMPLExxxxxx'}, 'cancellation_details': {'is_forced': True}, 'compartment_id': 'ocid1.compartment.oc1..xxxxxxEXAMPLExxxxxx', 'config_source': {'branch_name': 'branch_name_example', 'bucket_name': 'bucket_name_example', 'commit_id': 'ocid1.commit.oc1..xxxxxxEXAMPLExxxxxx', 'config_source_record_type': 'BITBUCKET_CLOUD_CONFIG_SOURCE', 'configuration_source_provider_id': 'ocid1.configurationsourceprovider.oc1..xxxxxxEXAMPLExxxxxx', 'namespace': 'namespace_example', 'project_id': 'ocid1.project.oc1..xxxxxxEXAMPLExxxxxx', 'region': 'us-phoenix-1', 'repository_id': 'ocid1.repository.oc1..xxxxxxEXAMPLExxxxxx', 'repository_url': 'repository_url_example', 'workspace_id': 'ocid1.workspace.oc1..xxxxxxEXAMPLExxxxxx'}, 'defined_tags': {'Operations': {'CostCenter': 'US'}}, 'display_name': 'display_name_example', 'failure_details': {'code': 'INTERNAL_SERVICE_ERROR', 'message': 'message_example'}, 'freeform_tags': {'Department': 'Finance'}, 'id': 'ocid1.resource.oc1..xxxxxxEXAMPLExxxxxx', 'is_provider_upgrade_required': True, 'is_third_party_provider_experience_enabled': True, 'job_operation_details': {'execution_plan_job_id': 'ocid1.executionplanjob.oc1..xxxxxxEXAMPLExxxxxx', 'execution_plan_rollback_job_id': 'ocid1.executionplanrollbackjob.oc1..xxxxxxEXAMPLExxxxxx', 'execution_plan_rollback_strategy': 'FROM_PLAN_ROLLBACK_JOB_ID', 'execution_plan_strategy': 'FROM_PLAN_JOB_ID', 'operation': 'APPLY', 'target_rollback_job_id': 'ocid1.targetrollbackjob.oc1..xxxxxxEXAMPLExxxxxx', 'terraform_advanced_options': {'detailed_log_level': 'ERROR', 'is_refresh_required': True, 'parallelism': 56}}, 'lifecycle_state': 'ACCEPTED', 'operation': 'PLAN', 'resolved_plan_job_id': 'ocid1.resolvedplanjob.oc1..xxxxxxEXAMPLExxxxxx', 'stack_id': 'ocid1.stack.oc1..xxxxxxEXAMPLExxxxxx', 'time_created': '2013-10-20T19:20:30+01:00', 'time_finished': '2013-10-20T19:20:30+01:00', 'variables': {}, 'working_directory': 'working_directory_example'}
 
apply_job_plan_resolution
complex
on success

   
is_auto_approved
boolean
on success
Specifies whether to use the configuration directly, without reference to a Plan job. `True` if using the configuration directly. Note that it is not necessary for a Plan job to have run successfully.

Sample:
True
   
is_use_latest_job_id
boolean
on success
Specifies whether to use the OCID of the most recently run plan job. `True` if using the latest job OCID. Must be a plan job that completed successfully.

Sample:
True
   
plan_job_id
string
on success
The OCID that specifies the most recently executed plan job.

Sample:
ocid1.planjob.oc1..xxxxxxEXAMPLExxxxxx
 
cancellation_details
complex
on success

   
is_forced
boolean
on success
Indicates whether a forced cancellation was requested for the job while it was running. A forced cancellation can result in an incorrect state file. For example, the state file might not reflect the exact state of the provisioned resources.

Sample:
True
 
compartment_id
string
on success
The OCID of the compartment in which the job's associated stack resides.

Sample:
ocid1.compartment.oc1..xxxxxxEXAMPLExxxxxx
 
config_source
complex
on success

   
branch_name
string
on success
The name of the branch within the Bitbucket Cloud repository.

Sample:
branch_name_example
   
bucket_name
string
on success
The name of the bucket that contains the Terraform configuration files.

Sample:
bucket_name_example
   
commit_id
string
on success
The unique identifier (SHA-1 hash) of the individual change to the Bitbucket Cloud repository.

Sample:
ocid1.commit.oc1..xxxxxxEXAMPLExxxxxx
   
config_source_record_type
string
on success
The type of configuration source to use for the Terraform configuration.

Sample:
BITBUCKET_CLOUD_CONFIG_SOURCE
   
configuration_source_provider_id
string
on success
Unique identifier (OCID) for the Bitbucket Cloud configuration source.

Sample:
ocid1.configurationsourceprovider.oc1..xxxxxxEXAMPLExxxxxx
   
namespace
string
on success
The Object Storage namespace that contains the bucket.

Sample:
namespace_example
   
project_id
string
on success
The OCID of the DevOps project.

Sample:
ocid1.project.oc1..xxxxxxEXAMPLExxxxxx
   
region
string
on success
The name of the bucket's region. Example: `us-phoenix-1`

Sample:
us-phoenix-1
   
repository_id
string
on success
Sample:
ocid1.repository.oc1..xxxxxxEXAMPLExxxxxx
   
repository_url
string
on success
The URL of the Bitbucket Cloud repository.

Sample:
repository_url_example
   
workspace_id
string
on success
The id of the workspace in Bitbucket Cloud for the configuration source.

Sample:
ocid1.workspace.oc1..xxxxxxEXAMPLExxxxxx
 
defined_tags
dictionary
on success
Defined tags for this resource. Each key is predefined and scoped to a namespace. For more information, see Resource Tags. Example: `{"Operations": {"CostCenter": "42"}}`

Sample:
{'Operations': {'CostCenter': 'US'}}
 
display_name
string
on success
The job's display name.

Sample:
display_name_example
 
failure_details
complex
on success

   
code
string
on success
Job failure reason.

Sample:
INTERNAL_SERVICE_ERROR
   
message
string
on success
A human-readable error string.

Sample:
message_example
 
freeform_tags
dictionary
on success
Free-form tags associated with this resource. Each tag is a key-value pair with no predefined name, type, or namespace. For more information, see Resource Tags. Example: `{"Department": "Finance"}`

Sample:
{'Department': 'Finance'}
 
id
string
on success
The OCID of the job.

Sample:
ocid1.resource.oc1..xxxxxxEXAMPLExxxxxx
 
is_provider_upgrade_required
boolean
on success
Specifies whether or not to upgrade provider versions. Within the version constraints of your Terraform configuration, use the latest versions available from the source of Terraform providers. For more information about this option, see L(Dependency Lock File (terraform.io),https://www.terraform.io/language/files/dependency-lock).

Sample:
True
 
is_third_party_provider_experience_enabled
boolean
on success
When `true`, the stack sources third-party Terraform providers from Terraform Registry and allows custom providers. For more information about stack sourcing of third-party Terraform providers, see Third-party Provider Configuration.

Sample:
True
 
job_operation_details
complex
on success

   
execution_plan_job_id
string
on success
The OCID of the plan job that contains the execution plan used for this job, or `null` if no execution plan was used.

Sample:
ocid1.executionplanjob.oc1..xxxxxxEXAMPLExxxxxx
   
execution_plan_rollback_job_id
string
on success
The OCID of a plan rollback job, for use when specifying `"FROM_PLAN_ROLLBACK_JOB_ID"` as the `executionPlanRollbackStrategy`.

Sample:
ocid1.executionplanrollbackjob.oc1..xxxxxxEXAMPLExxxxxx
   
execution_plan_rollback_strategy
string
on success
Specifies the source of the execution plan for rollback to apply. Use `AUTO_APPROVED` to run the job without an execution plan for rollback.

Sample:
FROM_PLAN_ROLLBACK_JOB_ID
   
execution_plan_strategy
string
on success
Specifies the source of the execution plan to apply. Use `AUTO_APPROVED` to run the job without an execution plan.

Sample:
FROM_PLAN_JOB_ID
   
operation
string
on success
Terraform-specific operation to execute.

Sample:
APPLY
   
target_rollback_job_id
string
on success
The OCID of a successful apply job, for use when specifying `"AUTO_APPROVED"` as the `executionPlanRollbackStrategy`.

Sample:
ocid1.targetrollbackjob.oc1..xxxxxxEXAMPLExxxxxx
   
terraform_advanced_options
complex
on success

     
detailed_log_level
string
on success
Enables detailed logs at the specified verbosity for running the job (operation).

Sample:
ERROR
     
is_refresh_required
boolean
on success
Specifies whether to refresh the state for each resource before running the job (operation). Refreshing the state can affect performance. Consider setting to `false` if the configuration includes several resources. Used with the following operations: `PLAN`, `APPLY`, `DESTROY`.

Sample:
True
     
parallelism
integer
on success
Limits the number of concurrent Terraform operations when walking the graph. Use this parameter to help debug Terraform issues or to accomplish certain special use cases. A higher value might cause resources to be throttled. Used with the following operations: `PLAN`, `APPLY`, `DESTROY`.

Sample:
56
 
lifecycle_state
string
on success
Current state of the specified job. For more information about job lifecycle states in Resource Manager, see Key Concepts.

Sample:
ACCEPTED
 
operation
string
on success
The type of job executing.

Sample:
PLAN
 
resolved_plan_job_id
string
on success
Deprecated. Use the property `executionPlanJobId` in `jobOperationDetails` instead. The plan job OCID that was used (if this was an apply job and was not auto-approved).

Sample:
ocid1.resolvedplanjob.oc1..xxxxxxEXAMPLExxxxxx
 
stack_id
string
on success
The OCID of the stack that is associated with the job.

Sample:
ocid1.stack.oc1..xxxxxxEXAMPLExxxxxx
 
time_created
string
on success
The date and time when the job was created. Format is defined by RFC3339. Example: `2020-01-25T21:10:29.600Z`

Sample:
2013-10-20T19:20:30+01:00
 
time_finished
string
on success
The date and time when the job stopped running, irrespective of whether the job ran successfully. Format is defined by RFC3339. Example: `2020-01-25T21:10:29.600Z`

Sample:
2013-10-20T19:20:30+01:00
 
variables
dictionary
on success
Terraform variables associated with this resource. Maximum number of variables supported is 250. The maximum size of each variable, including both name and value, is 8192 bytes. Example: `{"CompartmentId": "compartment-id-value"}`
 
working_directory
string
on success
File path to the directory to use for running Terraform. If not specified, the root directory is used. Required when using a zip Terraform configuration (`configSourceType` value of `ZIP_UPLOAD`) that contains folders. Ignored for the `configSourceType` value of `COMPARTMENT_CONFIG_SOURCE`. For more information about required and recommended file structure, see L(File Structure (Terraform Configurations for Resource Manager),https://docs.cloud.oracle.com/iaas/Content/ResourceManager/Concepts/terraformconfigresourcemanager.htm#filestructure).

Sample:
working_directory_example


Authors

  • Oracle (@oracle)