Add oci-v0.14.1 modules.

Oracle Cloud Infrastructure Ansible Modules provide an easy way to create and provision resources in Oracle Cloud Infrastructure (OCI) through Ansible. These modules allow you to author Ansible playbooks tha t help you automate the provisioning and configuring of Oracle Cloud Infrastructure services and resources, such as Compute, Load Balancing, Database, and other Oracle Cloud Infrastructure services.

This project includes Ansible cloud modules for OCI, its utility classes, documentation fragments, dynamic inventory, installer script, samples, docs and unit tests.

Contributors: - Debayan Gupta, Rohit Chaware, Sivakumar Thyagarajan

CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/).
+This project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
+
+## [1.0] - 2018-06-29
+
+### Added
+- In this first release of the OCI Ansible modules, the following Services are supported:
+  - Compute
+  - Block Storage
+  - Object Storage
+  - Networking
+  - Load Balancer
+  - Database Service
+  - Identity and Access Management
+- Provides a dynamic inventory script `oci_inventory.py` that helps you fetch the latest set of OCI compute instances and make them available for your playbooks to be executed upon.
+- Includes a catalog of Oracle Cloud Infrastructure Ansible module samples that illustrate using the modules to carry out common infrastructure provisioning and configuration tasks in the [samples](samples) directory. 
+
+

CONTRIBUTING.md

@@ -0,0 +1,19 @@
+# Contributing to the Oracle Cloud Infrastructure Python SDK
+
+_Copyright (c) 2016, 2018, Oracle and/or its affiliates. All rights reserved._
+
+Pull requests can be made under [The Oracle Contributor Agreement](https://www.oracle.com/technetwork/community/oca-486395.html) (OCA).
+
+For pull requests to be accepted, the bottom of your commit message must have the following line using your name and e-mail address as it appears in the OCA Signatories list.
+
+```
+  Signed-off-by: Your Name <you@example.org>
+```
+
+This can be automatically added to pull requests by committing with:
+
+```sh
+  git commit --signoff
+```
+
+Only pull requests from committers that can be verified as having signed the OCA can be accepted.

README.md

@@ -0,0 +1,63 @@
+# Oracle Cloud Infrastructure Ansible Modules
+
+## About
+
+Oracle Cloud Infrastructure Ansible Modules provide an easy way to create and provision resources in Oracle Cloud Infrastructure (OCI) through Ansible. These modules allow you to author Ansible playbooks that help you automate the provisioning and configuring of Oracle Cloud Infrastructure services and resources, such as Compute, Load Balancing, Database, and other Oracle Cloud Infrastructure services.
+
+**Services supported**
+- Block Volume
+- Compute
+- IAM
+- Load Balancing
+- Networking
+- Object Storage
+- Database
+
+The OCI Ansible modules are built using the [Oracle Cloud Infrastructure Python SDK](https://docs.us-phoenix-1.oraclecloud.com/Content/API/SDKDocs/pythonsdk.htm). The OCI Ansible modules honour the [SDK configuration](https://docs.us-phoenix-1.oraclecloud.com/Content/ToolsConfig.htm) when available.
+
+## Installation
+
+See the getting started guide (XXX) for instructions on using the installer script to install the Oracle Cloud Infrastructure Ansible Modules and its prerequisites in your host/Ansible controller node.
+
+## Samples
+
+This project includes a catalog of Oracle Cloud Infrastructure Ansible module samples that illustrate using the modules to carry out common infrastructure provisioning and configuration tasks in the `samples` directory. The samples are organized in groups associated with Oracle Cloud Infrastructure services:
+- Block Volume
+- Compute
+- Database
+- IAM
+- Load Balancing
+- Object Storage
+
+Begin by reviewing the Readme.md file that you will find in each sample's root directory.
+
+## Documentation
+
+Full documentation, including prerequisites, installation and configuration instructions, can be found here (XXX).
+
+## Help
+
+See the “Questions or Feedback” section here (XXX).
+
+## Changes
+
+See [CHANGELOG](CHANGELOG.md).
+
+## Contributing
+
+`oci-ansible-modules` is an open source project. See [CONTRIBUTING](CONTRIBUTING.md) for details.
+
+Oracle gratefully acknowledges the contributions to `oci-ansible-modules` that have been made by the community.
+
+## Known Issues
+
+You can find information on any known issues with the OCI ansible modules [here](https://docs.us-phoenix-1.oraclecloud.com/Content/knownissues.htm) and under the “Issues” tab of this
+project's [GitHub repository](https://github.com/oracle/oci-ansible-modules).
+
+## License
+
+Copyright (c) 2018 Oracle and/or its affiliates.
+
+This software is made available to you under the terms of the GPL 3.0 license or the Apache 2.0 license.
+
+See [LICENSE.txt](LICENSE.txt) for more details.

docs/dynamic-inventory-script.md

@@ -0,0 +1,175 @@
+# Oracle Cloud Infrastructure(OCI) Ansible Dynamic Inventory Script
+
+If you use Ansible to work with hosts provisioned in OCI, using a [static inventory file](https://docs.ansible.com/ansible/latest/user_guide/intro_inventory.html) may not work well, as OCI compute instances may get provisioned and terminated over time, or be created or managed by other external tools (API, console, SDK, Terraform etc). Using the OCI [dynamic inventory script](https://docs.ansible.com/ansible/latest/user_guide/intro_dynamic_inventory.html) will help ensure that the latest set of OCI compute instances are dynamically fetched and available for your playbooks to be executed upon.
+
+To use the OCI dynamic inventory script, grab the script and the default configuration files from
+- [inventory-script/oci_inventory.py](inventory-script/oci_inventory.py)
+- [inventory-script/oci_inventory.ini](inventory-script/oci_inventory.ini)
+to a local directory.
+
+## Dynamic Inventory Script
+
+### Prerequisites
+
+> Note: Before using the script, please ensure that you have a valid OCI SDK configuration. Refer [OCI SDK Configuration documentation](https://docs.us-phoenix-1.oraclecloud.com/Content/API/Concepts/sdkconfig.htm) for details on how to configure `~/.oci/config`.
+
+
+### Script and Configuration Details
+
+The `oci_inventory.py` script uses the OCI Python SDK to query OCI compute instances in your tenancy, and builds a dynamic inventory that can then be used in your Ansible playbooks. Arguments to the `oci_inventory.py` can help you control the configuration profile to use, the compartment to limit your search to, etc.
+
+The `oci_inventory.ini` configuration file can be optionally used to configure the OCI configuration profile to use, control how the inventory details are cached, and how hosts are named in your inventory.
+
+The `oci_inventory.py` script accepts the following command line arguments:
+```
+usage: oci_inventory.py [-h] [--list] [--host HOST] [-config CONFIG_FILE]
+              [--profile PROFILE] [--compartment COMPARTMENT]
+              [--refresh-cache] [--debug]
+
+optional arguments:
+  -h, --help            show this help message and exit
+  --list                List instances (default: True)
+  --host HOST           Get all information about a compute instance
+  -config CONFIG_FILE, --config-file CONFIG_FILE
+                        OCI config file location
+  --profile PROFILE     OCI config profile for connecting to OCI
+  --compartment COMPARTMENT
+                        Name of the compartment
+  --refresh-cache, -r   Force refresh of cache by making API requests to OCI
+                        (default: False - use cache files)
+  --debug               Send debug messages to STDERR
+```
+
+The `oci_inventory.py` script also accepts the following environment variables:
+
+| Environment Variable | Description |
+| -------------------- | ----------- |
+| OCI_CONFIG_FILE | Specifies the OCI SDK configuration file to use. |
+| OCI_INI_PATH | Specifies the inventory script's configuration file to use. |
+| OCI_CONFIG_PROFILE | Specifies the profile in the OCI SDK configuration file, to be used. |
+| OCI_USER_ID | Specifies the OCID of the OCI user to use to fetch the inventory. |
+| OCI_USER_FINGERPRINT | Specifies the OCI user's key-pair's fingerprint being used to use to fetch the inventory. |
+| OCI_USER_KEY_FILE | Specifies the full path including the filename of the private key of the OCI user being used to use to fetch the inventory. |
+| OCI_TENANCY | Specifies the OCID of the tenancy to use to fetch the inventory |
+| OCI_REGION |  Specifies the OCI Region to use to fetch the inventory |
+| OCI_USER_KEY_PASS_PHRASE | Specifies the passphrase of the key (if encrypted), to use to fetch the inventory. |
+| OCI_CACHE_DIR | Specifies the directory where cache files of the inventory script will reside. A file named "ansible-oci.cache" will be written to this directory. |
+| OCI_CACHE_MAX_AGE |  The number of seconds a cache file is considered valid. To disable caching and get the latest inventory from OCI, set this value to 0. |
+| OCI_HOSTNAME_FORMAT | Host naming format to use in the generated inventory. Use 'fqdn' to list hosts using the instance's Fully Qualified Domain Name (FQDN). Use 'public_ip' to list hosts using public IP address. Use 'private_ip' to list hosts using private IP address.|
+
+The order of precedence for the configuration used by the inventory script is:
+1. command line arguments
+1. environment variables
+1. options in script configuration file.
+
+The configuration file used for the script defaults to `./oci_inventory.ini` file. The OCI SDK configuration file defaults to `~/.oci/config` file. The script uses the `DEFAULT` profile from the config file if no profile name is specified.
+
+The generated inventory is grouped along the following axes:
+- region
+- compartment_name
+- availability domain
+- vcn_id
+- subnet_id
+- security_list_id
+- image_id
+- instance shape
+- freeform tags with group name as "tag_key=value"
+- defined tags with group name as "namespace#key=value"
+- metadata (key, value) with group name as "key=value"
+- extended metadata (key, value) with group name as "key=value"
+
+By default, all non-alphanumeric characters except HASH(#), EQUALS(=), PERIOD(.) and DASH(-) in group names and host names are replaced with an UNDERSCORE(_) when the inventory is generated, so that the names can be used as Ansible groups. To disable this replacement, set sanitize_names to False in the dynamic inventory settings file(default ./oci_inventory.ini). To also replace DASH(-) when sanitize_names is True, set replace_dash_in_names to True in the settings file.
+
+## How to Use
+
+### Using a Dynamic Inventory During Playbook Execution
+
+Ensure that you have correct OCI SDK configuration (and optionally an `oci_inventory.ini`). Invoke the `ansible-playbook` command using
+```sh
+$ ansible-playbook -i <path-to-inventory-file>/oci_inventory.py <your-playbook-using-the-generated-inventory>
+```
+or use the [`ANSIBLE_HOSTS`](https://docs.ansible.com/ansible/2.4/config.html#envvar-ANSIBLE_HOSTS) environment variable:
+```sh
+$ ANSIBLE_HOSTS=<path-to-inventory-file>/oci_inventory.py ansible-playbook <your-playbook-using-the-generated-inventory>
+```
+
+
+### To Disable Cache and Fetch Latest
+
+If you are running the dynamic inventory in a standalone manner, you can use "--refresh"/"-r" to ignore the cached inventory and fetch the latest inventory from OCI:
+```sh
+$ \<path-to-inventory-file\>/oci_inventory.py --refresh
+```
+
+If you are using the inventory script during an ansible-playbook invocation, set the `OCI_CACHE_MAX_AGE` environment variable to "0"(zero) to ignore the cache, and fetch the latest inventory from OCI: 
+```sh
+$ OCI_CACHE_MAX_AGE=0 ansible-playbook -i <path-to-inventory-file>/oci_inventory.py <your-playbook-using-the-generated-inventory>
+```
+
+### Debugging
+
+If you want to look at the dynamic inventory generated by the script, run it in with "--list", and check the output.
+
+```sh
+$ <path-to-inventory-file>/oci_inventory.py --list
+```
+
+To print additional debug information to STDERR, use
+```sh
+$ <path-to-inventory-file>/oci_inventory.py --debug
+```
+
+### Get a Single Host's Information
+
+The inventory script can also be configured to provide information about a single host. 
+
+```sh
+$ <path-to-inventory-file>/oci_inventory.py --host <host's-ip>
+```
+
+The script would then return the following variables for the specified host:
+```
+{
+    "availability_domain": "IwGV:US-ASHBURN-AD-1",
+    "compartment_id": "ocid1.compartment.oc1..xxxxxEXAMPLExxxxx",
+    "defined_tags": {},
+    "display_name": "ansible-test-instance-448",
+    "extended_metadata": {},
+    "freeform_tags": {},
+    "id": "ocid1.instance.oc1.iad.xxxxxEXAMPLExxxxx",
+    "image_id": "ocid1.image.oc1.iad.xxxxxEXAMPLExxxxx",
+    "ipxe_script": null,
+    "launch_mode": "CUSTOM",
+    "launch_options": {
+      "boot_volume_type": "ISCSI",
+      "firmware": "UEFI_64",
+      "network_type": "VFIO",
+      "remote_data_volume_type": "ISCSI"
+    },
+    "lifecycle_state": "AVAILABLE",
+    "metadata": {
+      "baz": "quux",
+      "foo": "bar"
+    },
+    "region": "iad",
+    "shape": "VM.Standard1.1",
+    "source_details": {
+      "image_id": "ocid1.image.oc1.iad.xxxxxEXAMPLExxxxx",
+      "source_type": "image"
+    },
+    "time_created": "2018-01-16T12:13:35.336000+00:00"
+}
+```
+
+## FAQs
+
+1. The generated inventory doesn't reflect all the compute instances in my tenancy.
+
+- Check if the OCI user ocid that you are specifying (either via OCI_USER or in the "profile" of your OCI SDK configuration file) has the policy permissions to list those instances. The dynamic inventory script current makes the following API operation calls. Ensure that the [corresponding permissions](https://docs.us-phoenix-1.oraclecloud.com/Content/Identity/Reference/corepolicyreference.htm#permissions) are given to the OCI user:
+  - ListCompartments
+  - ListVNICAttachments
+  - GetSubnet
+  - GetVCN
+  - GetVNIC
+  - GetInstance
+- The default `OCI_HOSTNAME_FORMAT` is "public_ip" and so the generated inventory would only contain compute instances with public IP. This is useful when your ansible controller node is outside the OCI VCN (as Ansible can only reach instances with public IPs). However if you are running Ansible in a compute instance within your OCI VCN that has access to all subnets within yuor VCN and can reach compute instances with private ips, set `OCI_HOSTNAME_FORMAT` to "private_ip" to fetch nodes with private IPs as well.

docs/faqs.md

@@ -0,0 +1,83 @@
+#### 1. How do I install the latest released version of the Ansible Cloud Modules?
+
+- Uninstall the current installed version of the modules using the `uninstall.py` script in the directory you had earlier cloned the OCI Ansible Cloud Modules repo to.
+```sh
+$ ./uninstall.py
+```
+- Perform a `git pull` on your local git repo to fetch and merge all changes in the OCI Ansible Cloud Modules Github repo at https://github.com/oracle/oci-ansible-modules.
+```sh
+$ git pull
+```
+
+- Checkout the tag corresponding to the latest release. The latest Ansible modules  releases are available at
+[https://github.com/oracle/oci-ansible-modules/releases](https://github.com/oracle/oci-ansible-modules/releases).
+
+```sh
+$ git checkout <release>
+```
+
+- Install the latest release
+```sh
+$ ./install.py
+```
+
+#### 2. How do I get web-documentation for the OCI Ansible Cloud Modules?
+
+> Please stay tuned. This is work-in-progress.
+
+Until this is available, to obtain access to detailed information about using Ansible modules  in the CLI, including documentation of a module's configurable options, samples, return values, and so forth, use the ansible-doc command on the module's name. For example, to get the documentation for the oci_bucket_facts module, execute the following command:
+
+```sh
+$ ansible-doc oci_bucket_facts
+```
+
+#### 3. How do I enable `debug` mode for the OCI Ansible Cloud Modules?
+
+
+*  Set the `log_requests` variable in your ~/.oci/config to `True` to enable Request logging in the OCI python SDK as described in https://github.com/oracle/oci-python-sdk/blob/master/docs/logging.rst
+*  Export an environment variable to enable DEBUG mode for our Ansible modules
+`$ export LOG_LEVEL="DEBUG"`
+
+All subsequent debug messages from an ansible playbook execution using the OCI Ansible Cloud Modules
+`$ ansible-playbook ....`
+would go to `/tmp/oci_ansible_module.log` (the default logging location for our modules).
+
+
+#### 4. In a Mac OSX controller node, I am seeing "ImportError: No module named yaml" when executing a playbook, in spite of observing that I have ansible and its requirements including PyYAML installed in my python setup.
+
+If you are running on macOS, and you have python installed by brew, you may see a ImportError(for example: `ImportError: No module named yaml`).
+To resolve this, you must override the `ansible_python_interpreter` configuration option. Setting the inventory variable `ansible_python_interpreter` on any host will allow Ansible to auto-replace the interpreter used when executing python modules.
+
+`ansible_python_interpreter` configuration option can be set in inventory file. For example:
+
+```[control-node]
+localhost ansible_python_interpreter="/usr/local/Cellar/python/2.7.14_3/bin/python2.7"
+```
+
+OR `ansible_python_interpreter` configuration option can be set using `-e` command line option:
+
+```sh
+$ ansible-playbook sample-playbook.yml -e 'ansible_python_interpreter=/usr/local/Cellar/python/2.7.14_3/bin/python2.7'
+```
+
+#### 5. `ansible-doc` fails with an error when using the modules through an ansible role
+
+`ansible-doc` fails with a documentation error when using the Ansible Cloud Modules through the `oci-ansible-role` ansible role.
+
+> $ ansible-doc oci_bucket_facts
+> [ERROR]: module oci_bucket_facts has a documentation error formatting or is missing documentation
+
+The documentation fragments shipped by an ansible module that is delivered by an ansible role, is not consulted by `ansible-doc`. To get around this problem, use the installer script to install the OCI Ansible Cloud Modules.
+
+#### 6. How do I use the `oci_inventory.py` dynamic inventory script?
+
+In addition to the OCI Ansible Cloud Modules, this project also provide a [dynamic inventory](https://docs.ansible.com/ansible/latest/user_guide/intro_dynamic_inventory.html) script for OCI that you can use to construct a dynamic inventory of your OCI compute instances. For more details, see our how-to documentation at [using the dynamic inventory script](dynamic-inventory-script.md).
+
+
+#### 7. Any security guidelines or best practices?
+
+The OCI Ansible Cloud Modules uses the authentication information specified in the standard OCI SDK configuration file (https://oracle-cloud-infrastructure-python-sdk.readthedocs.io/en/latest/installation.html#configuring-the-sdk) while creating and configuring OCI resources.
+
+> *Caution*: IAM credentials referenced in the OCI SDK configuration file, grants access to resources. It is important to secure these credentials to prevent unauthorized access to Oracle Cloud Infrastructure resources. Follow the guidelines in https://docs.us-phoenix-1.oraclecloud.com/Content/Security/Reference/iam_security.htm#IAMCredentials to secure the IAM credentials in the controller node where you run ansible playbooks that uses these modules.
+
+The OCI Ansible Cloud Modules allows the authentication information specified in the OCI SDK configuration file to be overridden using module options and environment variables. Please refer to the ansible module documentation of the OCI Ansible Cloud Modules for more details. Oracle recommends the use of OCI SDK configuration file to specify authentication information. Use the "profiles" feature in the OCI SDK configuration file to support different users. The use of environment variables and ansible module options to override Authentication information must be avoided in production scenarios. While distributing roles that use the OCI Ansible Cloud Modules, ensure that no IAM credentials are included with the roles.