Gce migration docs (#51838)

* migration docs for gce, with example playbook

* Update docs/docsite/rst/scenario_guides/guide_gce.rst

Co-Authored-By: rambleraptor <alexstephen@google.com>
This commit is contained in:
Alex Stephen 2019-04-15 14:30:36 -07:00 committed by Alicia Cozine
parent a005dcfbbd
commit 91a664a93e

View file

@ -81,7 +81,7 @@ For the GCE modules you can specify the credentials as arguments:
* ``project``: id of the project
* ``scopes``: The specific scopes that you want the actions to use.
For example, to create a new IP address using the `gcp_compute_address` module,
For example, to create a new IP address using the ``gcp_compute_address`` module,
you can use the following configuration:
.. code-block:: yaml
@ -252,3 +252,60 @@ Note that use of the "add_host" module above creates a temporary, in-memory grou
in the 'new_instances' group, if so desired. Any sort of arbitrary configuration is possible at this point.
For more information about Google Cloud, please visit the `Google Cloud website <https://cloud.google.com>`_.
Migration Guides
----------------
gce.py -> gcp_compute_instance.py
`````````````````````````````````
As of Ansible 2.8, we're encouraging everyone to move from the ``gce`` module to the
``gcp_compute_instance`` module. The ``gcp_compute_instance`` module has better
support for all of GCP's features, fewer dependencies, more flexibility, and
better supports GCP's authentication systems.
The ``gcp_compute_instance`` module supports all of the features of the ``gce``
module (and more!). Below is a mapping of ``gce`` fields over to
``gcp_compute_instance`` fields.
============================ ========================================== ======================
gce.py gcp_compute_instance.py Notes
============================ ========================================== ======================
state state/status State on gce has multiple values: "present", "absent", "stopped", "started", "terminated". State on gcp_compute_instance is used to describe if the instance exists (present) or does not (absent). Status is used to describe if the instance is "started", "stopped" or "terminated".
image disks[].initialize_params.source_image You'll need to create a single disk using the disks[] parameter and set it to be the boot disk (disks[].boot = true)
image_family disks[].initialize_params.source_image See above.
external_projects disks[].initialize_params.source_image The name of the source_image will include the name of the project.
instance_names Use a loop or multiple tasks. Using loops is a more Ansible-centric way of creating multiple instances and gives you the most flexibility.
service_account_email service_accounts[].email This is the service_account email address that you want the instance to be associated with. It is not the service_account email address that is used for the credentials necessary to create the instance.
service_account_permissions service_accounts[].scopes These are the permissions you want to grant to the instance.
pem_file Not supported. We recommend using JSON service account credentials instead of PEM files.
credentials_file service_account_file
project_id project
name name This field does not accept an array of names. Use a loop to create multiple instances.
num_instances Use a loop For maximum flexibility, we're encouraging users to use Ansible features to create multiple instances, rather than letting the module do it for you.
network network_interfaces[].network
subnetwork network_interfaces[].subnetwork
persistent_boot_disk disks[].type = 'PERSISTENT'
disks disks[]
ip_forward can_ip_forward
external_ip network_interfaces[].access_configs.nat_ip This field takes multiple types of values. You can create an IP address with ``gcp_compute_address`` and place the name/output of the address here. You can also place the string value of the IP address's GCP name or the actual IP address.
disks_auto_delete disks[].auto_delete
preemptible scheduling.preemptible
disk_size disks[].initialize_params.disk_size_gb
============================ ========================================== ======================
An example playbook is below:
.. code:: yaml
gcp_compute_instance:
name: "{{ item }}"
machine_type: n1-standard-1
... # any other settings
zone: us-central1-a
project: "my-project"
auth_kind: "service_account_file"
service_account_file: "~/my_account.json"
state: present
with_items:
- instance-1
- instance-2