mirror of
https://github.com/ansible-collections/community.general.git
synced 2024-09-14 20:13:21 +02:00
04220478da
* Fewer connection: local lines in module examples and scenario guides The line 'connection: local' is not required. See ./docs/docsite/rst/inventory/implicit_localhost.rst
254 lines
8.8 KiB
ReStructuredText
254 lines
8.8 KiB
ReStructuredText
Google Cloud Platform Guide
|
|
===========================
|
|
|
|
.. gce_intro:
|
|
|
|
Introduction
|
|
--------------------------
|
|
|
|
Ansible + Google have been working together on a set of auto-generated
|
|
Ansible modules designed to consistently and comprehensively cover the entirety
|
|
of the Google Cloud Platform.
|
|
|
|
Ansible contains modules for managing Google Cloud Platform resources,
|
|
including creating instances, controlling network access, working with
|
|
persistent disks, managing load balancers, and a lot more.
|
|
|
|
These new modules can be found under a new consistent name scheme "gcp_*"
|
|
(Note: gcp_target_proxy and gcp_url_map are legacy modules, despite the "gcp_*"
|
|
name. Please use gcp_compute_target_proxy and gcp_compute_url_map instead).
|
|
|
|
Additionally, the gcp_compute inventory plugin can discover all GCE instances
|
|
and make them automatically available in your Ansible inventory.
|
|
|
|
You may see a collection of other GCP modules that do not conform to this
|
|
naming convention. These are the original modules primarily developed by the
|
|
Ansible community. You will find some overlapping functionality such as with
|
|
the "gce" module and the new "gcp_compute_instance" module. Either can be
|
|
used, but you may experience issues trying to use them together.
|
|
|
|
While the community GCP modules are not going away, Google is investing effort
|
|
into the new "gcp_*" modules. Google is committed to ensuring the Ansible
|
|
community has a great experience with GCP and therefore recommends adopting
|
|
these new modules if possible.
|
|
|
|
|
|
Requisites
|
|
---------------
|
|
The Google Cloud Platform (GCP) modules require both the ``requests`` and the
|
|
``google-auth`` libraries to be installed.
|
|
|
|
.. code-block:: bash
|
|
|
|
$ pip install requests google-auth
|
|
|
|
Alternatively for RHEL / CentOS, the ``python-requests`` package is also
|
|
available to satisfy ``requests`` libraries.
|
|
|
|
.. code-block:: bash
|
|
|
|
$ yum install python-requests
|
|
|
|
Credentials
|
|
-----------
|
|
It's easy to create a GCP account with credentials for Ansible. You have multiple options to
|
|
get your credentials - here are two of the most common options:
|
|
|
|
* Service Accounts (Recommended): Use JSON service accounts with specific permissions.
|
|
* Machine Accounts: Use the permissions associated with the GCP Instance you're using Ansible on.
|
|
|
|
For the following examples, we'll be using service account credentials.
|
|
|
|
To work with the GCP modules, you'll first need to get some credentials in the
|
|
JSON format:
|
|
|
|
1. `Create a Service Account <https://developers.google.com/identity/protocols/OAuth2ServiceAccount#creatinganaccount>`_
|
|
2. `Download JSON credentials <https://support.google.com/cloud/answer/6158849?hl=en&ref_topic=6262490#serviceaccounts>`_
|
|
|
|
Once you have your credentials, there are two different ways to provide them to Ansible:
|
|
|
|
* by specifying them directly as module parameters
|
|
* by setting environment variables
|
|
|
|
Providing Credentials as Module Parameters
|
|
``````````````````````````````````````````
|
|
|
|
For the GCE modules you can specify the credentials as arguments:
|
|
|
|
* ``auth_kind``: type of authentication being used (choices: machineaccount, serviceaccount, application)
|
|
* ``service_account_email``: email associated with the project
|
|
* ``service_account_file``: path to the JSON credentials file
|
|
* ``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,
|
|
you can use the following configuration:
|
|
|
|
.. code-block:: yaml
|
|
|
|
- name: Create IP address
|
|
hosts: localhost
|
|
gather_facts: no
|
|
|
|
vars:
|
|
service_account_file: /home/my_account.json
|
|
project: my-project
|
|
auth_kind: serviceaccount
|
|
scopes:
|
|
- www.googleapis.com/auth/compute
|
|
|
|
tasks:
|
|
|
|
- name: Allocate an IP Address
|
|
gcp_compute_address:
|
|
state: present
|
|
name: 'test-address1'
|
|
region: 'us-west1'
|
|
project: "{{ project }}"
|
|
auth_kind: "{{ auth_kind }}"
|
|
service_account_file: "{{ service_account_file }}"
|
|
scopes: "{{ scopes }}"
|
|
|
|
Providing Credentials as Environment Variables
|
|
``````````````````````````````````````````````
|
|
|
|
Set the following environment variables before running Ansible in order to configure your credentials:
|
|
|
|
.. code-block:: bash
|
|
|
|
GCP_AUTH_KIND
|
|
GCP_SERVICE_ACCOUNT_EMAIL
|
|
GCP_SERVICE_ACCOUNT_FILE
|
|
GCP_SCOPES
|
|
|
|
GCE Dynamic Inventory
|
|
---------------------
|
|
|
|
The best way to interact with your hosts is to use the gcp_compute inventory plugin, which dynamically queries GCE and tells Ansible what nodes can be managed.
|
|
|
|
To be able to use this GCE dynamic inventory plugin, you need to enable it first by specifying the following in the ``ansible.cfg`` file:
|
|
|
|
.. code-block:: ini
|
|
|
|
[inventory]
|
|
enable_plugins = gcp_compute
|
|
|
|
Then, create a file that ends in ``.gcp.yml`` in your root directory.
|
|
|
|
The gcp_compute inventory script takes in the same authentication information as any module.
|
|
|
|
Here's an example of a valid inventory file:
|
|
|
|
.. code-block:: yaml
|
|
|
|
plugin: gcp_compute
|
|
projects:
|
|
- graphite-playground
|
|
auth_kind: serviceaccount
|
|
service_account_file: /home/alexstephen/my_account.json
|
|
|
|
|
|
Executing ``ansible-inventory --list -i <filename>.gcp.yml`` will create a list of GCP instances that are ready to be configured using Ansible.
|
|
|
|
Create an instance
|
|
``````````````````
|
|
|
|
The full range of GCP modules provide the ability to create a wide variety of
|
|
GCP resources with the full support of the entire GCP API.
|
|
|
|
The following playbook creates a GCE Instance. This instance relies on a GCP
|
|
network and a Disk. By creating the Disk and Network separately, we can give as
|
|
much detail as necessary about how we want the disk and network formatted. By
|
|
registering a Disk/Network to a variable, we can simply insert the variable
|
|
into the instance task. The gcp_compute_instance module will figure out the
|
|
rest.
|
|
|
|
.. code-block:: yaml
|
|
|
|
- name: Create an instance
|
|
hosts: localhost
|
|
gather_facts: no
|
|
vars:
|
|
project: my-project
|
|
auth_kind: serviceaccount
|
|
service_account_file: /home/my_account.json
|
|
zone: "us-central1-a"
|
|
region: "us-central1"
|
|
|
|
tasks:
|
|
- name: create a disk
|
|
gcp_compute_disk:
|
|
name: 'disk-instance'
|
|
size_gb: 50
|
|
source_image: 'projects/ubuntu-os-cloud/global/images/family/ubuntu-1604-lts'
|
|
zone: "{{ zone }}"
|
|
project: "{{ gcp_project }}"
|
|
auth_kind: "{{ gcp_cred_kind }}"
|
|
service_account_file: "{{ gcp_cred_file }}"
|
|
scopes:
|
|
- https://www.googleapis.com/auth/compute
|
|
state: present
|
|
register: disk
|
|
- name: create a network
|
|
gcp_compute_network:
|
|
name: 'network-instance'
|
|
project: "{{ gcp_project }}"
|
|
auth_kind: "{{ gcp_cred_kind }}"
|
|
service_account_file: "{{ gcp_cred_file }}"
|
|
scopes:
|
|
- https://www.googleapis.com/auth/compute
|
|
state: present
|
|
register: network
|
|
- name: create a address
|
|
gcp_compute_address:
|
|
name: 'address-instance'
|
|
region: "{{ region }}"
|
|
project: "{{ gcp_project }}"
|
|
auth_kind: "{{ gcp_cred_kind }}"
|
|
service_account_file: "{{ gcp_cred_file }}"
|
|
scopes:
|
|
- https://www.googleapis.com/auth/compute
|
|
state: present
|
|
register: address
|
|
- name: create a instance
|
|
gcp_compute_instance:
|
|
state: present
|
|
name: test-vm
|
|
machine_type: n1-standard-1
|
|
disks:
|
|
- auto_delete: true
|
|
boot: true
|
|
source: "{{ disk }}"
|
|
network_interfaces:
|
|
- network: "{{ network }}"
|
|
access_configs:
|
|
- name: 'External NAT'
|
|
nat_ip: "{{ address }}"
|
|
type: 'ONE_TO_ONE_NAT'
|
|
zone: "{{ zone }}"
|
|
project: "{{ gcp_project }}"
|
|
auth_kind: "{{ gcp_cred_kind }}"
|
|
service_account_file: "{{ gcp_cred_file }}"
|
|
scopes:
|
|
- https://www.googleapis.com/auth/compute
|
|
register: instance
|
|
|
|
- name: Wait for SSH to come up
|
|
wait_for: host={{ instance.address }} port=22 delay=10 timeout=60
|
|
|
|
- name: Add host to groupname
|
|
add_host: hostname={{ instance.address }} groupname=new_instances
|
|
|
|
|
|
- name: Manage new instances
|
|
hosts: new_instances
|
|
connection: ssh
|
|
sudo: True
|
|
roles:
|
|
- base_configuration
|
|
- production_server
|
|
|
|
Note that use of the "add_host" module above creates a temporary, in-memory group. This means that a play in the same playbook can then manage machines
|
|
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>`_.
|