From 828e683ea1a6cda32922be253ff9e7ab9b649166 Mon Sep 17 00:00:00 2001 From: leslitagordita Date: Fri, 24 May 2019 16:26:14 -0400 Subject: [PATCH 1/9] [New] Deploy Linodes Using Ansible and the linode_v4 Module --- .../deploy-linodes-using-ansible/index.md | 378 ++++++++++++++++++ 1 file changed, 378 insertions(+) create mode 100644 docs/applications/configuration-management/deploy-linodes-using-ansible/index.md diff --git a/docs/applications/configuration-management/deploy-linodes-using-ansible/index.md b/docs/applications/configuration-management/deploy-linodes-using-ansible/index.md new file mode 100644 index 00000000000..9189c214641 --- /dev/null +++ b/docs/applications/configuration-management/deploy-linodes-using-ansible/index.md @@ -0,0 +1,378 @@ +--- +author: + name: Linode Community + email: docs@linode.com +description: 'In this guide you learn how to deploy and manage Linodes using Ansible and the `linode_v4` module. You will also create an Ansible inventory for your Linode infrastructure using the dynamic inventory plugin for Linode.' +keywords: ['ansible','Linode module','dynamic inventory','configuration management'] +license: '[CC BY-ND 4.0](https://creativecommons.org/licenses/by-nd/4.0)' +published: 2019-06-04 +modified: 2019-06-04 +modified_by: + name: Linode +title: "Deploy Linodes Using Ansible and the linode_v4 Module" +contributor: + name: Linode +external_resources: +- '[Ansible Best Practices](https://docs.ansible.com/ansible/latest/user_guide/playbooks_best_practices.html)' +--- +Ansible is a popular open-source tool that can be used to automate common IT tasks, like cloud provisioning and configuration management. With [Ansible's 2.8 release](https://docs.ansible.com/ansible/latest/roadmap/ROADMAP_2_8.html), you can deploy Linode instances using our latest [API (v4)](https://developers.linode.com/api/v4/). Ansible's `linode_v4` module adds the functionality needed to deploy and manage Linodes via the command line or in your [Ansible Playbooks](/docs/applications/configuration-management/automatically-configure-servers-with-ansible-and-playbooks/). While the dynamic inventory plugin for Linode helps you source your Ansible inventory directly from the Linode API (v4). + +In this guide you learn how to: + +* Deploy and manage Linodes using Ansible and the `linode_v4` module. +* Create an Ansible inventory for your Linode infrastructure using the dynamic inventory plugin for Linode. + +{{< caution >}} +This guide’s example instructions will create a [1 GB Nanode](https://www.linode.com/pricing) billable resource on your Linode account. If you do not want to keep using the Nanode that you create, be sure to [delete the resource](#delete-your-resources) when you have finished the guide. + +If you remove the resources afterward, you will only be billed for the hour(s) that the resources were present on your account. +{{}} + +## Before You Begin + +{{< note >}} +The steps outlined in this guide require [Ansible version 2.8](https://github.com/ansible/ansible/releases/tag/v2.8.0). +{{}} + +- Install Ansible on your computer. Use the steps in the [Installing Ansible](https://www.linode.com/docs/applications/configuration-management/learn-how-to-install-ansible-and-run-playbooks/#installing-ansible) section of the [Learn How to Install Ansible and Run Playbooks](/docs/applications/configuration-management/learn-how-to-install-ansible-and-run-playbooks/) guide. + +- Ensure you have Python version 2.7 or higher installed on your computer. Issue the following command to check your system's Python version: + + python --version + +- Install the official [Python library for the Linode API v4](https://github.com/linode/linode_api4-python). + + pip install linode_api4 + +- Genearate a Linode API v4 access token with permission to read and write Linodes. You can follow the [Get an Access Token](https://linode.com/docs/platform/api/getting-started-with-the-linode-api/#get-an-access-token) section of the [Getting Started with the Linode API](https://linode.com/docs/platform/api/getting-started-with-the-linode-api/) guide if you do not already have one. + +## Configure Ansible + +The Ansible configuration file is used to adjust Ansible's default system settings. Ansible will search for a configuration file in the directories listed below, in the order specified, and apply the first configuration values it finds: + +- `ANSIBLE_CONFIG` environment variable pointing to a configuration file location. If passed, it will override the default Ansible configuration file. +- `ansible.cfg` file in the current directory +- `~/.ansible.cfg` in the home directory +- `/etc/ansible/ansible.cfg` + +In this section, you will create an Ansible configuration file and add options to disable host key checking and to whitelist the Linode inventory plugin. The Ansible configuration file will be located in your home directory, however, it could exist in any of the locations listed above. See [Ansible's official documentation](https://docs.ansible.com/ansible/latest/reference_appendices/config.html#common-options) for a full list of available configuration settings. + +{{< caution >}} +When storing your Ansible configuration file, ensure that its corresponding directory does not have world-writable permissions. This could pose a security risk that allows malicious users to use Ansible to exploit your local system and remote infrastructure. At minimum, the directory should restrict access to particular users and groups. For example, you can create an `ansible` group, only add privileged users to the `ansible` group, and update the Ansible configuration file's directory to have `764` permissions. See the [Linux Users and Groups](/docs/tools-reference/linux-users-and-groups/) guide for more information on permissions. +{{}} + +1. Create a directory to hold all your Ansible related files: + + mkdir development + +1. Create the Ansible configuration file, `ansible.cfg` in the `development` directory and add the `host_key_checking` and `enable_plugins` options. + + {{< file "~/development/ansible.cfg">}} +[defaults] +host_key_checking = False +vault_password_file = ./development/vault-pass +[inventory] +enable_plugins = linode + {{}} + + - `host_key_checking = False` will allow Ansible to SSH into hosts without having to accept the remote server's host key. This will disable host key checking globally. + - `vault_password_file = ./development/vault-pass` is used to specify a Vault password file to use whenever Ansible Vault requires a password. Ansible Vault offers several options for password management. To learn more password management, read Ansible's [Providing Vault Passwords](https://docs.ansible.com/ansible/latest/user_guide/vault.html#providing-vault-passwords) documentation. + - `enable_plugins = linode` enables the Linode dynamic inventory plugin. + +## Create a Linode Instance + +You can now begin to create Linode instances using Ansible. In this section, you will create an Ansible Playbook that can deploy Linodes. + +### Create your Linode Playbook + +1. Create a directory to store your Ansible Playbooks: + + mkdir ~/development + +1. Expose your Linode access token in your shell environment. Replace the value of `mylinodetoken` with your own token. + + export LINODE_TOKEN='mylinodetoken' + +1. Using your preferred text editor, create the `Create Linode` Playbook file and include the following values: + + {{< file "~/development/linode_create.yml" yaml >}} +- name: Create Linode + hosts: localhost + vars_files: + - /home/username/development/group_vars/example_group/vars + tasks: + - name: Create a new Linode. + linode_v4: + label: "{{ label }}{{ 100 |random }}" + access_token: "{{ token }}" + type: g6-nanode-1 + region: us-east + image: linode/debian9 + root_pass: "{{ password }}" + authorized_keys: "{{ ssh_keys }}" + group: example_group + tags: example_group + state: present + register: my_linode + {{}} + + - The Playbook `my_linode` contains the `Create Linode` play, which will be executed on `hosts: localhost`. This means the Ansible playbook will execute on the local system and use it as a vehicle to deploy the remote Linode instances. + - The `vars_files` key provides the location of a local file that contains variable values to populate in the play. The value of any variables defined in the vars file will substitute any Jinja template variables used in the Playbook. Jinja template variables are any vars between `{{ my_var }}`. + - The `Create a new Linode` task calls the `linode_v4` module and provides all required module parameters as arguments, plus additional arguments to configure the Linode's deployment. For details on each parameter, see the [linode_v4 Module Parameters](#linode-v4-module-parameters) section. + + {{< note >}} + Usage of `groups` is deprecated, but still supported by Linode's API v4. The [Linode dynamic inventory module](#linode-dynamic-inventory-module) requires groups to generate an Ansible inventory and will be used later in this guide. + {{}} + + - The`register` keyword defines a variable name, `my_linode` that will store `linode_v4` module return data. For instance, you could reference the `my_linode` variable later in your Playbook to complete other actions using data about your Linode. This keyword is not required to deploy a Linode instance, but represents a common way to declare and use variables in Ansible Playbooks. For example, the task in the snippet below will use Ansible's [debug module](https://docs.ansible.com/ansible/2.4/debug_module.html) and the `my_linode` variable to print out a message with the Linode instance's ID and IPv4 address during Playbook execution. + + {{< file >}} +... +- name: Print info about my Linode instance + debug: + msg: "ID is {{ my_linode.instance.id }} IP is {{ my_linode.instance.ipv4 }}" + {{}} + +### Create the Variables File + +In the previous section, you created the Create Linode Playbook to deploy Linode instances and made use of Jinja template variables. In this section, you will create the variables file to provide values to those template variables. + +1. Create the directory to store your Playbook's variable files. The directory is structured to group your variable files by inventory group. This directory structure supports the use of file level encryption that Ansible Vault can detect and parse. Although it is not relevant to this guide's example, it will be used as a best practice. + + mkdir -p ~/development/group_vars/example_group/ + +1. Create the variables file and populate it with the example variables. You can replace the values with your own. + + {{< file "~/development/group_vars/example_group/vars.yml">}} +ssh_keys: > + ['ssh-rsa AAAAB3N..5bYqyRaQ== user@mycomputer', '~/.ssh/id_rsa.pub'] +label: simple-linode- + {{}} + + - The `ssh_keys` example passes a list of two public SSH keys. The first provides the string value of the key, while the second provides a local public key file location. + + {{< disclosure-note "Configure your SSH Agent" >}} +If your SSH Keys are passphrase-protected, you should add the keys to your SSH Agent so that Ansible does not hang when running Playbooks on the remote Linode. The following instructions are for Linux systems: + +1. Run the following command; if you stored your private key in another location, update the path that’s passed to ssh-add accordingly: + + eval $(ssh-agent) && ssh-add ~/.ssh/id_rsa + + If you start a new terminal, you will need to run the commands in this step again before having access to the keys stored in your SSH Agent. + {{}} + + - `label` provides a label prefix that will be concatenated with a random number. This occurs when the Create Linode Playbook's Jinja templating for the `label` argument is parsed (`label: "{{ label }}{{ 100 |random }}"`). + +#### Encrypt Sensitive Variables with Ansible Vault + +Ansible Vault allows you to encrypt sensitive data, like passwords or tokens, to keep them from being exposed in your Ansible Playbooks or Roles. You will take advantage of this functionality to keep your Linode instance's `password` and `access_token` encrypted within the variables file. + +{{< note >}} +Ansible Vault can also encrypt entire files containing sensitive values. View Ansible's documentation on [Vault](https://docs.ansible.com/ansible/latest/user_guide/vault.html#what-can-be-encrypted-with-vault) for more information. +{{}} + +1. Create your Ansible Vault password file and add your password to the file. Remember the location of the password file was configured in the `ansible.cfg` file in the [Configure Ansible](#configure-ansible) section of this guide. + + {{< file "~/development/vault-pass">}} +My.ANS1BLEvault-c00lPassw0rd + {{}} + +1. Encrypt the value of your Linode's root user password using Ansible Vault. Replace `My.c00lPassw0rd` with your own strong password that conforms to the [`root_pass` parameter's](#linode-v4-module-parameters) constraints. + + ansible-vault encrypt_string 'My.c00lPassw0rd' --name 'password' + + You will see a similar output: + + {{< output >}} + password: !vault | + $ANSIBLE_VAULT;1.1;AES256 + 30376134633639613832373335313062366536313334316465303462656664333064373933393831 + 3432313261613532346134633761316363363535326333360a626431376265373133653535373238 + 38323166666665376366663964343830633462623537623065356364343831316439396462343935 + 6233646239363434380a383433643763373066633535366137346638613261353064353466303734 + 3833
+Encryption successful + {{}} + +1. Copy the generated output and add it to your `vars.yml` file. + +1. Encrypt the value of your access token. Replace the value of `86210...1e1c6bd` with your own access token. + + ansible-vault encrypt_string '86210...1e1c6bd' --name 'token' + +1. Copy the generated output and it to the bottom of your `vars.yml` file. + + The final `vars.yml` file should resemble the example below: + + {{< file "~/development/group_vars/example_group/vars.yml">}} +ssh_keys: > + ['ssh-rsa AAAAB3N..5bYqyRaQ== user@mycomputer', '~/.ssh/id_rsa.pub'] +label: simple-linode- +password: !vault | + $ANSIBLE_VAULT;1.1;AES256 + 30376134633639613832373335313062366536313334316465303462656664333064373933393831 + 3432313261613532346134633761316363363535326333360a626431376265373133653535373238 + 38323166666665376366663964343830633462623537623065356364343831316439396462343935 + 6233646239363434380a383433643763373066633535366137346638613261353064353466303734 + 3833 +token: !vault | + $ANSIBLE_VAULT;1.1;AES256 + 65363565316233613963653465613661316134333164623962643834383632646439306566623061 + 3938393939373039373135663239633162336530373738300a316661373731623538306164363434 + 31656434356431353734666633656534343237333662613036653137396235353833313430626534 + 3330323437653835660a303865636365303532373864613632323930343265343665393432326231 + 61313635653463333630636631336539643430326662373137303166303739616262643338373834 + 34613532353031333731336339396233623533326130376431346462633832353432316163373833 + 35316333626530643736636332323161353139306533633961376432623161626132353933373661 + 36663135323664663130 + {{}} + +### Run the Ansible Playbook + +You are now ready to run the Create Linode Playbook. When you run the Playbook, a 1 GB Nanode will be deployed in the Newark data center. + +1. Run your playbook to create your Linode instances. + + ansible-playbook ~/development/linode_create.yml + + You will see a similar output: + + PLAY [Create Linode] ********************************************************************* + + TASK [Gathering Facts] ******************************************************************* + ok: [localhost] + + TASK [Create a new Linode.] ************************************************************** + changed: [localhost] + + PLAY RECAP ******************************************************************************* + localhost : ok=3 changed=1 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0 + +### linode_v4 Module Parameters + +| Parameter | Data type/Status | Usage | +| --------- | -------- | ------| +| `access_token` | string, *required* | Your Linode API v4 access token. The token should have permission to read and write Linodes. The token can also be specified by exposing the `LINODE_ACCESS_TOKEN` environment variable. | +| `authorized_keys` | list | A list of SSH public keys or SSH public key file locations on your local system, for example, `['averylongstring','~/.ssh/id_rsa.pub']`. The public key will be stored in the `/root/.ssh/authorized_keys` file on your Linode. Ansible will use the public key to SSH into your Linodes as the root user and execute your Playbooks.| +| `group` | string, *deprecated* | The Linode instance's group. Please note, group labelling is deprecated but still supported. The encouraged method for marking instances is to use tags. This parameter must be provided to use the Linode dynamic inventory module. | +| `image` | string | The Image ID to deploy the Linode disk from. Official Linode Images start with `linode/`, while your private images start with `private/`. For example, use `linode/ubuntu18.04` to deploy a Linode instance with the Ubuntu 18.04 image. This is a required parameter only when creating Linode instances.

To view a list of all available Linode images, issue the following command:

`curl https://api.linode.com/v4/images`.| +| `label` | string, *required* | The Linode instance label. The label is used by the module as the main determiner for idempotence and must be a unique value.

Linode labels have the following constraints:

• Must start with an alpha character.
• May only consist of alphanumeric characters, dashes (-), underscores (_) or periods (.).
• Cannot have two dashes (--), underscores (__) or periods (..) in a row. | +| `region` | string | The region where the Linode will be located. This is a required parameter only when creating Linode instances.

To view a list of all available regions, issue the following command:

`curl https://api.linode.com/v4/regions`. | +| `root_pass` | string | The password for the root user. If not specified, one will be generated. This generated password will be available in the task success JSON.

The root password must conform to the following constraints:

• May only use alphanumerics, punctuation, spaces, and tabs.
• Must contain at least two of the following characters classes: upper-case letters, lower-case letters, digits, punctuation. | +| `state` | string, *required* | The desired instance state. The accepted values are `absent` and `present`. | +| `tags` | list | The user-defined labels attached to Linodes. Tags are used for grouping Linodes in a way that is relevant to the user. | +| `type` | string, | The Linode instance's plan type. The plan type determines your Linode's [hardware resources](/docs/platform/how-to-choose-a-linode-plan/#hardware-resource-definitions) and its [pricing](https://www.linode.com/pricing#all).

To view a list of all available Linode types including pricing and specifications for each type, issue the following command:

`curl https://api.linode.com/v4/linode/types`. | + +## The Linode Dynamic Inventory Plugin + +Ansible uses *inventories* to manage different hosts that make up your infrastructure. This allows you to execute tasks on specific parts of your infrastructure. By default, Ansible will look in `/etc/ansible/hosts` for inventory, however, you can designate a different location for your inventory file and use multiple inventory files that represent your infrastructure. To support infrastructures that shifts over time, Ansible offers the ability to track inventory from dynamic sources, like cloud providers. The Ansible dynamic inventory plugin for Linode can be used to source your inventory from Linode's API v4. In this section, you will use the Linode plugin to source your Ansible deployed Linode inventory. + +{{< note >}} +The dynamic inventory plugin for Linode was enabled in the Ansible configuration file created in the [Configure Ansible](#configure-ansible) section of this guide. +{{}} + +### Configure the Plugin + +1. Configure the Ansible dynamic inventory plugin for Linode by creating a file named `linode.yml`. + + {{< file "~/development/linode.yml"yaml>}} +plugin: linode +regions: + - us-east +groups: + - example_group +types: + - g6-nanode-1 + {{}} + + - The configuration file will create an inventory for any Linodes on your account that are in the `us-east` region, part of the `example_group` group and of type `g6-nanode-1`. Any Linodes that are not part of the `example_group` group, but that fulfill the `us-east` region and `g6-nanode-type` type will be displayed as ungrouped. All other Linodes will be excluded from the dynamic inventory. For more information on all supported parameters, see the [Plugin Parameters](#plugin-parameters) section. + +### Run the Inventory Plugin + +1. Export your Linode API v4 access token to the shell environment. `LINODE_ACCESS_TOKEN` must be used as the environment variable name. Replace `mytoken` with your own access token. + + export LINODE_ACCESS_TOKEN='mytoken' + +1. Run the Linode dynamic inventory plugin. + + ansible-inventory -i ~/development/linode.yml --graph + + You should see a similar output. The output may vary depending on the Linodes already deployed to your account and the parameter values you pass. + + @all: + |--@example_group: + | |--simple-linode-29 + + For a more detailed output including all Linode instance configurations, issue the following command: + + ansible-inventory -i ~/development/linode.yml --graph --vars + +1. Before you can communicate with your Linode instances using the dynamic inventory plugin, you will need to add your Linode's IPv4 address and label to your `/etc/hosts` file. + + The Linode Dynamic Inventory Plugin assumes that the Linodes in your account have labels that correspond to hostnames that are in your resolver search path, `/etc/hosts`. This means you will have to create an entry in your `/etc/hosts` file to map the Linode's IPv4 address to its hostname. + + A [pull request](https://github.com/ansible/ansible/pull/51196) currently exists to support using a public IP, private IP or hostname. This change will enable the inventory plugin to be used with infrastructure that does not have DNS hostnames or hostnames that match Linode labels. + + To add your deployed Linode instance to the `/etc/hosts` file: + + - Retrieve your Linode instance's IPv4 address: + + ansible-inventory -i ansible/linode.yml --graph --vars | grep 'ipv4\|simple-linode' + + Your output will resemble the following: + + | |--simple-linode-36 + | | |--{ipv4 = [u'192.0.2.0']} + | | |--{label = simple-linode-36} + + - Open the `/etc/hosts` file and add your Linode's IPv4 address and label: + + {{< file "/etc/hosts">}} +127.0.0.1 localhost +192.0.2.0 simple-linode-29 + {{}} + +1. Verify that you can communicate with your grouped inventory by pinging the Linodes. The ping command will use the dynamic inventory plugin configuration file to target `example_group`. The `u root` option will run the command as root on the Linode hosts. + + ansible -m ping example_group -i ~/development/linode.yml -u root + + You should see a similar output: + + simple-linode-29 | SUCCESS => { + "ansible_facts": { + "discovered_interpreter_python": "/usr/bin/python" + }, + "changed": false, + "ping": "pong" + } + +### Plugin Parameters + +| Parameter | Data type/Status | Usage | +| --------- | -------- | ------| +| `access_token` | string, *required* | Your Linode API v4 access token. The token should have permission to read and write Linodes. The token can also be specified by exposing the `LINODE_ACCESS_TOKEN` environment variable. | +| `plugin` | string, *required* | The plugin name. The value must always be `linode` in order to use the dynamic inventory plugin for Linode. | +| `regions` | list | The Linode region with which to populate the inventory. For example, `us-east` is possible value for this parameter.

To view a list of all available Linode images, issue the following command:

`curl https://api.linode.com/v4/images`. | +| `types` | list | The Linode type with which to populate the inventory. For example, `g6-nanode-1` is a possible value for this parameter.

To view a list of all available Linode types including pricing and specifications for each type, issue the following command:

`curl https://api.linode.com/v4/linode/types`. | +| `groups` | list | The Linode group with which to populate the inventory. Please note, group labelling is deprecated but still supported. The encouraged method for marking instances is to use tags. This parameter must be provided to use the Linode dynamic inventory module. | + +## Delete Your Resources + +1. To delete the Linode instance created in this guide, create a Delete Linode Playbook with the following content in the example. Replace the value of `label` with your Linode's label: + + {{< file "~/development/linode_delete.yml" yaml>}} +- name: Delete Linode + hosts: localhost + vars_files: + - /home/lsalazar/ansible/group_vars/crazy_cool_group/vars + tasks: + - name: Delete your Linode Instance. + linode_v4: + label: simple-linode-29 + state: absent + {{}} + +1. Run the Delete Linode Playbook: + + ansible-playbook linode_delete.yml + From a7ae9be6234c225d7c601b0a3238a4b9b79d2693 Mon Sep 17 00:00:00 2001 From: hzoppetti Date: Fri, 7 Jun 2019 14:46:25 -0400 Subject: [PATCH 2/9] ansible linode tech edit --- .../deploy-linodes-using-ansible/index.md | 45 ++++++++++++------- 1 file changed, 28 insertions(+), 17 deletions(-) diff --git a/docs/applications/configuration-management/deploy-linodes-using-ansible/index.md b/docs/applications/configuration-management/deploy-linodes-using-ansible/index.md index 9189c214641..d62d5f9bf36 100644 --- a/docs/applications/configuration-management/deploy-linodes-using-ansible/index.md +++ b/docs/applications/configuration-management/deploy-linodes-using-ansible/index.md @@ -44,7 +44,7 @@ The steps outlined in this guide require [Ansible version 2.8](https://github.co pip install linode_api4 -- Genearate a Linode API v4 access token with permission to read and write Linodes. You can follow the [Get an Access Token](https://linode.com/docs/platform/api/getting-started-with-the-linode-api/#get-an-access-token) section of the [Getting Started with the Linode API](https://linode.com/docs/platform/api/getting-started-with-the-linode-api/) guide if you do not already have one. +- Generate a Linode API v4 access token with permission to read and write Linodes. You can follow the [Get an Access Token](https://linode.com/docs/platform/api/getting-started-with-the-linode-api/#get-an-access-token) section of the [Getting Started with the Linode API](https://linode.com/docs/platform/api/getting-started-with-the-linode-api/) guide if you do not already have one. ## Configure Ansible @@ -55,7 +55,7 @@ The Ansible configuration file is used to adjust Ansible's default system settin - `~/.ansible.cfg` in the home directory - `/etc/ansible/ansible.cfg` -In this section, you will create an Ansible configuration file and add options to disable host key checking and to whitelist the Linode inventory plugin. The Ansible configuration file will be located in your home directory, however, it could exist in any of the locations listed above. See [Ansible's official documentation](https://docs.ansible.com/ansible/latest/reference_appendices/config.html#common-options) for a full list of available configuration settings. +In this section, you will create an Ansible configuration file and add options to disable host key checking and to whitelist the Linode inventory plugin. The Ansible configuration file will be located in a development directory that you create, however, it could exist in any of the locations listed above. See [Ansible's official documentation](https://docs.ansible.com/ansible/latest/reference_appendices/config.html#common-options) for a full list of available configuration settings. {{< caution >}} When storing your Ansible configuration file, ensure that its corresponding directory does not have world-writable permissions. This could pose a security risk that allows malicious users to use Ansible to exploit your local system and remote infrastructure. At minimum, the directory should restrict access to particular users and groups. For example, you can create an `ansible` group, only add privileged users to the `ansible` group, and update the Ansible configuration file's directory to have `764` permissions. See the [Linux Users and Groups](/docs/tools-reference/linux-users-and-groups/) guide for more information on permissions. @@ -63,20 +63,20 @@ When storing your Ansible configuration file, ensure that its corresponding dire 1. Create a directory to hold all your Ansible related files: - mkdir development + mkdir ~/development 1. Create the Ansible configuration file, `ansible.cfg` in the `development` directory and add the `host_key_checking` and `enable_plugins` options. {{< file "~/development/ansible.cfg">}} [defaults] host_key_checking = False -vault_password_file = ./development/vault-pass +VAULT_PASSWORD_FILE = /home/username/development/vault-pass [inventory] enable_plugins = linode {{}} - `host_key_checking = False` will allow Ansible to SSH into hosts without having to accept the remote server's host key. This will disable host key checking globally. - - `vault_password_file = ./development/vault-pass` is used to specify a Vault password file to use whenever Ansible Vault requires a password. Ansible Vault offers several options for password management. To learn more password management, read Ansible's [Providing Vault Passwords](https://docs.ansible.com/ansible/latest/user_guide/vault.html#providing-vault-passwords) documentation. + - `vault_password_file = ./development/vault-pass` is used to specify a Vault password file to use whenever Ansible Vault requires a password. Ansible Vault offers several options for password management. To learn more password management, read Ansible's [Providing Vault Passwords](https://docs.ansible.com/ansible/latest/user_guide/vault.html#providing-vault-passwords) documentation. Note: remember to replace `username` with your username. - `enable_plugins = linode` enables the Linode dynamic inventory plugin. ## Create a Linode Instance @@ -85,7 +85,7 @@ You can now begin to create Linode instances using Ansible. In this section, you ### Create your Linode Playbook -1. Create a directory to store your Ansible Playbooks: +1. If you haven't already, create a directory to store your Ansible Playbooks: mkdir ~/development @@ -117,7 +117,7 @@ You can now begin to create Linode instances using Ansible. In this section, you {{}} - The Playbook `my_linode` contains the `Create Linode` play, which will be executed on `hosts: localhost`. This means the Ansible playbook will execute on the local system and use it as a vehicle to deploy the remote Linode instances. - - The `vars_files` key provides the location of a local file that contains variable values to populate in the play. The value of any variables defined in the vars file will substitute any Jinja template variables used in the Playbook. Jinja template variables are any vars between `{{ my_var }}`. + - The `vars_files` key provides the location of a local file that contains variable values to populate in the play. The value of any variables defined in the vars file will substitute any Jinja template variables used in the Playbook. Jinja template variables are any vars between `{{ my_var }}`. Note: remember to replace `username` with your username. - The `Create a new Linode` task calls the `linode_v4` module and provides all required module parameters as arguments, plus additional arguments to configure the Linode's deployment. For details on each parameter, see the [linode_v4 Module Parameters](#linode-v4-module-parameters) section. {{< note >}} @@ -143,13 +143,13 @@ In the previous section, you created the Create Linode Playbook to deploy Linode 1. Create the variables file and populate it with the example variables. You can replace the values with your own. - {{< file "~/development/group_vars/example_group/vars.yml">}} + {{< file "~/development/group_vars/example_group/vars">}} ssh_keys: > - ['ssh-rsa AAAAB3N..5bYqyRaQ== user@mycomputer', '~/.ssh/id_rsa.pub'] + ['ssh-rsa AAAAB3N..5bYqyRaQ== user@mycomputer'] label: simple-linode- {{}} - - The `ssh_keys` example passes a list of two public SSH keys. The first provides the string value of the key, while the second provides a local public key file location. + - The `ssh_keys` example passes a list of public SSH keys. You can pass either the string values of the keys as a comma delimited list or the public key file location. {{< disclosure-note "Configure your SSH Agent" >}} If your SSH Keys are passphrase-protected, you should add the keys to your SSH Agent so that Ansible does not hang when running Playbooks on the remote Linode. The following instructions are for Linux systems: @@ -194,17 +194,17 @@ My.ANS1BLEvault-c00lPassw0rd Encryption successful {{}} -1. Copy the generated output and add it to your `vars.yml` file. +1. Copy the generated output and add it to your `vars` file. 1. Encrypt the value of your access token. Replace the value of `86210...1e1c6bd` with your own access token. ansible-vault encrypt_string '86210...1e1c6bd' --name 'token' -1. Copy the generated output and it to the bottom of your `vars.yml` file. +1. Copy the generated output and it to the bottom of your `vars` file. - The final `vars.yml` file should resemble the example below: + The final `vars` file should resemble the example below: - {{< file "~/development/group_vars/example_group/vars.yml">}} + {{< file "~/development/group_vars/example_group/vars">}} ssh_keys: > ['ssh-rsa AAAAB3N..5bYqyRaQ== user@mycomputer', '~/.ssh/id_rsa.pub'] label: simple-linode- @@ -229,7 +229,7 @@ token: !vault | ### Run the Ansible Playbook -You are now ready to run the Create Linode Playbook. When you run the Playbook, a 1 GB Nanode will be deployed in the Newark data center. +You are now ready to run the Create Linode Playbook. When you run the Playbook, a 1 GB Nanode will be deployed in the Newark data center. Note: you want to run the following commands from the directory where your Ansible config file is located. 1. Run your playbook to create your Linode instances. @@ -317,7 +317,7 @@ types: - Retrieve your Linode instance's IPv4 address: - ansible-inventory -i ansible/linode.yml --graph --vars | grep 'ipv4\|simple-linode' + ansible-inventory -i ~/development/linode.yml --graph --vars | grep 'ipv4\|simple-linode' Your output will resemble the following: @@ -332,6 +332,17 @@ types: 192.0.2.0 simple-linode-29 {{}} + - Add the inventory option to the `ansible.cfg` file. + + {{< file "~/development/ansible.cfg">}} +[defaults] +host_key_checking = False +VAULT_PASSWORD_FILE = /home/username/development/vault-pass +inventory = ./etc/hosts +[inventory] +enable_plugins = linode + {{}} + 1. Verify that you can communicate with your grouped inventory by pinging the Linodes. The ping command will use the dynamic inventory plugin configuration file to target `example_group`. The `u root` option will run the command as root on the Linode hosts. ansible -m ping example_group -i ~/development/linode.yml -u root @@ -364,7 +375,7 @@ types: - name: Delete Linode hosts: localhost vars_files: - - /home/lsalazar/ansible/group_vars/crazy_cool_group/vars + - /home/username/development/group_vars/example_group/vars tasks: - name: Delete your Linode Instance. linode_v4: From 90437ea64cb60cedb3ada116c125d3e417cfd4e8 Mon Sep 17 00:00:00 2001 From: hzoppetti Date: Mon, 10 Jun 2019 06:30:46 -0400 Subject: [PATCH 3/9] ansible linode tech edit making sure I have all the changes back to Leslie --- .../deploy-linodes-using-ansible/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/applications/configuration-management/deploy-linodes-using-ansible/index.md b/docs/applications/configuration-management/deploy-linodes-using-ansible/index.md index d62d5f9bf36..b78431f6507 100644 --- a/docs/applications/configuration-management/deploy-linodes-using-ansible/index.md +++ b/docs/applications/configuration-management/deploy-linodes-using-ansible/index.md @@ -76,7 +76,7 @@ enable_plugins = linode {{}} - `host_key_checking = False` will allow Ansible to SSH into hosts without having to accept the remote server's host key. This will disable host key checking globally. - - `vault_password_file = ./development/vault-pass` is used to specify a Vault password file to use whenever Ansible Vault requires a password. Ansible Vault offers several options for password management. To learn more password management, read Ansible's [Providing Vault Passwords](https://docs.ansible.com/ansible/latest/user_guide/vault.html#providing-vault-passwords) documentation. Note: remember to replace `username` with your username. + - `vault_password_file = /home/username/development/vault-pass` is used to specify a Vault password file to use whenever Ansible Vault requires a password. Ansible Vault offers several options for password management. To learn more password management, read Ansible's [Providing Vault Passwords](https://docs.ansible.com/ansible/latest/user_guide/vault.html#providing-vault-passwords) documentation. Note: remember to replace `username` with your username. - `enable_plugins = linode` enables the Linode dynamic inventory plugin. ## Create a Linode Instance @@ -206,7 +206,7 @@ Encryption successful {{< file "~/development/group_vars/example_group/vars">}} ssh_keys: > - ['ssh-rsa AAAAB3N..5bYqyRaQ== user@mycomputer', '~/.ssh/id_rsa.pub'] + ['ssh-rsa AAAAB3N..5bYqyRaQ== user@mycomputer'] label: simple-linode- password: !vault | $ANSIBLE_VAULT;1.1;AES256 From f1929ee7f718dac6bf9dab632981bae04d714e60 Mon Sep 17 00:00:00 2001 From: hzoppetti Date: Mon, 10 Jun 2019 09:56:05 -0400 Subject: [PATCH 4/9] added dictionary terms alphanumerics and idempotence --- ci/vale/dictionary.txt | 2 ++ 1 file changed, 2 insertions(+) diff --git a/ci/vale/dictionary.txt b/ci/vale/dictionary.txt index c144d17e5b2..53855802a5c 100644 --- a/ci/vale/dictionary.txt +++ b/ci/vale/dictionary.txt @@ -17,6 +17,7 @@ ajp aker alives allmasquerade +alphanumerics amavis amavisd amd64 @@ -543,6 +544,7 @@ icinga icingacli icmp icmpv6 +idempotence ident identrust idlist From 5f32fd0215e4aa1d0ec678836ccd11e70407c1f3 Mon Sep 17 00:00:00 2001 From: leslitagordita Date: Mon, 10 Jun 2019 12:49:11 -0400 Subject: [PATCH 5/9] Tech edits related to reproducing reported behavior Initial tech edit ran into errors related to host key checking. I ran through steps to try to reproduce the errors, but was not able to. Some misc. changes were found while editing w/ Heather and those have been added. --- .../deploy-linodes-using-ansible/index.md | 32 +++++++++---------- 1 file changed, 15 insertions(+), 17 deletions(-) diff --git a/docs/applications/configuration-management/deploy-linodes-using-ansible/index.md b/docs/applications/configuration-management/deploy-linodes-using-ansible/index.md index 9189c214641..c55cbb019d0 100644 --- a/docs/applications/configuration-management/deploy-linodes-using-ansible/index.md +++ b/docs/applications/configuration-management/deploy-linodes-using-ansible/index.md @@ -46,6 +46,8 @@ The steps outlined in this guide require [Ansible version 2.8](https://github.co - Genearate a Linode API v4 access token with permission to read and write Linodes. You can follow the [Get an Access Token](https://linode.com/docs/platform/api/getting-started-with-the-linode-api/#get-an-access-token) section of the [Getting Started with the Linode API](https://linode.com/docs/platform/api/getting-started-with-the-linode-api/) guide if you do not already have one. +- [Create an authentication Key-pair](/docs/security/securing-your-server/#create-an-authentication-key-pair) if your computer does not already have one. + ## Configure Ansible The Ansible configuration file is used to adjust Ansible's default system settings. Ansible will search for a configuration file in the directories listed below, in the order specified, and apply the first configuration values it finds: @@ -61,9 +63,9 @@ In this section, you will create an Ansible configuration file and add options t When storing your Ansible configuration file, ensure that its corresponding directory does not have world-writable permissions. This could pose a security risk that allows malicious users to use Ansible to exploit your local system and remote infrastructure. At minimum, the directory should restrict access to particular users and groups. For example, you can create an `ansible` group, only add privileged users to the `ansible` group, and update the Ansible configuration file's directory to have `764` permissions. See the [Linux Users and Groups](/docs/tools-reference/linux-users-and-groups/) guide for more information on permissions. {{}} -1. Create a directory to hold all your Ansible related files: +1. In your home directory, create a directory to hold all your Ansible related files and move into the directory: - mkdir development + mkdir development && cd development 1. Create the Ansible configuration file, `ansible.cfg` in the `development` directory and add the `host_key_checking` and `enable_plugins` options. @@ -85,13 +87,9 @@ You can now begin to create Linode instances using Ansible. In this section, you ### Create your Linode Playbook -1. Create a directory to store your Ansible Playbooks: - - mkdir ~/development +1. Ensure you are in the `development` directory that you created in the [Configure Ansible](/docs/applications/configuration-management/deploy-linodes-using-ansible/#create-a-linode-instance) section: -1. Expose your Linode access token in your shell environment. Replace the value of `mylinodetoken` with your own token. - - export LINODE_TOKEN='mylinodetoken' + cd ~/development 1. Using your preferred text editor, create the `Create Linode` Playbook file and include the following values: @@ -99,7 +97,7 @@ You can now begin to create Linode instances using Ansible. In this section, you - name: Create Linode hosts: localhost vars_files: - - /home/username/development/group_vars/example_group/vars + - ./group_vars/example_group/vars tasks: - name: Create a new Linode. linode_v4: @@ -143,7 +141,7 @@ In the previous section, you created the Create Linode Playbook to deploy Linode 1. Create the variables file and populate it with the example variables. You can replace the values with your own. - {{< file "~/development/group_vars/example_group/vars.yml">}} + {{< file "~/development/group_vars/example_group/vars">}} ssh_keys: > ['ssh-rsa AAAAB3N..5bYqyRaQ== user@mycomputer', '~/.ssh/id_rsa.pub'] label: simple-linode- @@ -194,15 +192,15 @@ My.ANS1BLEvault-c00lPassw0rd Encryption successful {{}} -1. Copy the generated output and add it to your `vars.yml` file. +1. Copy the generated output and add it to your `vars` file. 1. Encrypt the value of your access token. Replace the value of `86210...1e1c6bd` with your own access token. ansible-vault encrypt_string '86210...1e1c6bd' --name 'token' -1. Copy the generated output and it to the bottom of your `vars.yml` file. +1. Copy the generated output and it to the bottom of your `vars` file. - The final `vars.yml` file should resemble the example below: + The final `vars` file should resemble the example below: {{< file "~/development/group_vars/example_group/vars.yml">}} ssh_keys: > @@ -231,7 +229,7 @@ token: !vault | You are now ready to run the Create Linode Playbook. When you run the Playbook, a 1 GB Nanode will be deployed in the Newark data center. -1. Run your playbook to create your Linode instances. +1. Run your playbook to create your Linode instances. Ensure you are in the `development` directory when running the command. ansible-playbook ~/development/linode_create.yml @@ -317,7 +315,7 @@ types: - Retrieve your Linode instance's IPv4 address: - ansible-inventory -i ansible/linode.yml --graph --vars | grep 'ipv4\|simple-linode' + ansible-inventory -i ~/development/linode.yml --graph --vars | grep 'ipv4\|simple-linode' Your output will resemble the following: @@ -364,7 +362,7 @@ types: - name: Delete Linode hosts: localhost vars_files: - - /home/lsalazar/ansible/group_vars/crazy_cool_group/vars + - ./group_vars/example_group/vars tasks: - name: Delete your Linode Instance. linode_v4: @@ -374,5 +372,5 @@ types: 1. Run the Delete Linode Playbook: - ansible-playbook linode_delete.yml + ansible-playbook ~/development/linode_delete.yml From fa43777c2490fb6c5fbaf276906ef193012b12a0 Mon Sep 17 00:00:00 2001 From: leslitagordita Date: Mon, 10 Jun 2019 13:15:01 -0400 Subject: [PATCH 6/9] Add relative path to config for consistency. Readd directory as example value for `ssh_keys` in var file. --- .../deploy-linodes-using-ansible/index.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/applications/configuration-management/deploy-linodes-using-ansible/index.md b/docs/applications/configuration-management/deploy-linodes-using-ansible/index.md index fe3f88a9502..e5581de24de 100644 --- a/docs/applications/configuration-management/deploy-linodes-using-ansible/index.md +++ b/docs/applications/configuration-management/deploy-linodes-using-ansible/index.md @@ -72,7 +72,7 @@ When storing your Ansible configuration file, ensure that its corresponding dire {{< file "~/development/ansible.cfg">}} [defaults] host_key_checking = False -VAULT_PASSWORD_FILE = /home/username/development/vault-pass +VAULT_PASSWORD_FILE = ./vault-pass [inventory] enable_plugins = linode {{}} @@ -143,7 +143,7 @@ In the previous section, you created the Create Linode Playbook to deploy Linode {{< file "~/development/group_vars/example_group/vars">}} ssh_keys: > - ['ssh-rsa AAAAB3N..5bYqyRaQ== user@mycomputer'] + ['ssh-rsa AAAAB3N..5bYqyRaQ== user@mycomputer', '~/.ssh/id_rsa.pub'] label: simple-linode- {{}} @@ -204,7 +204,7 @@ Encryption successful {{< file "~/development/group_vars/example_group/vars">}} ssh_keys: > - ['ssh-rsa AAAAB3N..5bYqyRaQ== user@mycomputer'] + ['ssh-rsa AAAAB3N..5bYqyRaQ== user@mycomputer', '~/.ssh/id_rsa.pub'] label: simple-linode- password: !vault | $ANSIBLE_VAULT;1.1;AES256 From 320a66a2140d6074914bea6ffe540e0b599be564 Mon Sep 17 00:00:00 2001 From: hzoppetti Date: Mon, 10 Jun 2019 14:48:42 -0400 Subject: [PATCH 7/9] updating to remove a few things that didn't need changing back and small copy edits --- .../deploy-linodes-using-ansible/index.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/applications/configuration-management/deploy-linodes-using-ansible/index.md b/docs/applications/configuration-management/deploy-linodes-using-ansible/index.md index e5581de24de..ecf3529595d 100644 --- a/docs/applications/configuration-management/deploy-linodes-using-ansible/index.md +++ b/docs/applications/configuration-management/deploy-linodes-using-ansible/index.md @@ -78,7 +78,7 @@ enable_plugins = linode {{}} - `host_key_checking = False` will allow Ansible to SSH into hosts without having to accept the remote server's host key. This will disable host key checking globally. - - `vault_password_file = /home/username/development/vault-pass` is used to specify a Vault password file to use whenever Ansible Vault requires a password. Ansible Vault offers several options for password management. To learn more password management, read Ansible's [Providing Vault Passwords](https://docs.ansible.com/ansible/latest/user_guide/vault.html#providing-vault-passwords) documentation. Note: remember to replace `username` with your username. + - `VAULT_PASSWORD_FILE = ./vault-pass` is used to specify a Vault password file to use whenever Ansible Vault requires a password. Ansible Vault offers several options for password management. To learn more password management, read Ansible's [Providing Vault Passwords](https://docs.ansible.com/ansible/latest/user_guide/vault.html#providing-vault-passwords) documentation. - `enable_plugins = linode` enables the Linode dynamic inventory plugin. ## Create a Linode Instance @@ -115,7 +115,7 @@ You can now begin to create Linode instances using Ansible. In this section, you {{}} - The Playbook `my_linode` contains the `Create Linode` play, which will be executed on `hosts: localhost`. This means the Ansible playbook will execute on the local system and use it as a vehicle to deploy the remote Linode instances. - - The `vars_files` key provides the location of a local file that contains variable values to populate in the play. The value of any variables defined in the vars file will substitute any Jinja template variables used in the Playbook. Jinja template variables are any vars between `{{ my_var }}`. Note: remember to replace `username` with your username. + - The `vars_files` key provides the location of a local file that contains variable values to populate in the play. The value of any variables defined in the vars file will substitute any Jinja template variables used in the Playbook. Jinja template variables are any vars between `{{ my_var }}`. - The `Create a new Linode` task calls the `linode_v4` module and provides all required module parameters as arguments, plus additional arguments to configure the Linode's deployment. For details on each parameter, see the [linode_v4 Module Parameters](#linode-v4-module-parameters) section. {{< note >}} @@ -147,7 +147,7 @@ ssh_keys: > label: simple-linode- {{}} - - The `ssh_keys` example passes a list of public SSH keys. You can pass either the string values of the keys as a comma delimited list or the public key file location. + - The `ssh_keys` example passes a list of two public SSH keys. The first provides the string value of the key, while the second provides a local public key file location. {{< disclosure-note "Configure your SSH Agent" >}} If your SSH Keys are passphrase-protected, you should add the keys to your SSH Agent so that Ansible does not hang when running Playbooks on the remote Linode. The following instructions are for Linux systems: @@ -227,9 +227,9 @@ token: !vault | ### Run the Ansible Playbook -You are now ready to run the Create Linode Playbook. When you run the Playbook, a 1 GB Nanode will be deployed in the Newark data center. Note: you want to run the following commands from the directory where your Ansible config file is located. +You are now ready to run the Create Linode Playbook. When you run the Playbook, a 1 GB Nanode will be deployed in the Newark data center. Note: you want to run Ansible commands from the directory where your `ansible.cfg` file is located. -1. Run your playbook to create your Linode instances. Ensure you are in the `development` directory when running the command. +1. Run your playbook to create your Linode instances. ansible-playbook ~/development/linode_create.yml @@ -263,7 +263,7 @@ You are now ready to run the Create Linode Playbook. When you run the Playbook, ## The Linode Dynamic Inventory Plugin -Ansible uses *inventories* to manage different hosts that make up your infrastructure. This allows you to execute tasks on specific parts of your infrastructure. By default, Ansible will look in `/etc/ansible/hosts` for inventory, however, you can designate a different location for your inventory file and use multiple inventory files that represent your infrastructure. To support infrastructures that shifts over time, Ansible offers the ability to track inventory from dynamic sources, like cloud providers. The Ansible dynamic inventory plugin for Linode can be used to source your inventory from Linode's API v4. In this section, you will use the Linode plugin to source your Ansible deployed Linode inventory. +Ansible uses *inventories* to manage different hosts that make up your infrastructure. This allows you to execute tasks on specific parts of your infrastructure. By default, Ansible will look in `/etc/ansible/hosts` for inventory, however, you can designate a different location for your inventory file and use multiple inventory files that represent your infrastructure. To support infrastructures that shift over time, Ansible offers the ability to track inventory from dynamic sources, like cloud providers. The Ansible dynamic inventory plugin for Linode can be used to source your inventory from Linode's API v4. In this section, you will use the Linode plugin to source your Ansible deployed Linode inventory. {{< note >}} The dynamic inventory plugin for Linode was enabled in the Ansible configuration file created in the [Configure Ansible](#configure-ansible) section of this guide. @@ -281,7 +281,7 @@ groups: - example_group types: - g6-nanode-1 - {{}} +{{}} - The configuration file will create an inventory for any Linodes on your account that are in the `us-east` region, part of the `example_group` group and of type `g6-nanode-1`. Any Linodes that are not part of the `example_group` group, but that fulfill the `us-east` region and `g6-nanode-type` type will be displayed as ungrouped. All other Linodes will be excluded from the dynamic inventory. For more information on all supported parameters, see the [Plugin Parameters](#plugin-parameters) section. @@ -335,8 +335,8 @@ types: {{< file "~/development/ansible.cfg">}} [defaults] host_key_checking = False -VAULT_PASSWORD_FILE = /home/username/development/vault-pass -inventory = ./etc/hosts +VAULT_PASSWORD_FILE = ~/development/vault-pass +inventory = /etc/hosts [inventory] enable_plugins = linode {{}} From 2bb12ad5d2f0849f88ae5757a792a8673475021e Mon Sep 17 00:00:00 2001 From: hzoppetti Date: Mon, 10 Jun 2019 15:05:04 -0400 Subject: [PATCH 8/9] final changes --- .../deploy-linodes-using-ansible/index.md | 11 ----------- 1 file changed, 11 deletions(-) diff --git a/docs/applications/configuration-management/deploy-linodes-using-ansible/index.md b/docs/applications/configuration-management/deploy-linodes-using-ansible/index.md index ecf3529595d..76b05ba64d5 100644 --- a/docs/applications/configuration-management/deploy-linodes-using-ansible/index.md +++ b/docs/applications/configuration-management/deploy-linodes-using-ansible/index.md @@ -330,17 +330,6 @@ types: 192.0.2.0 simple-linode-29 {{}} - - Add the inventory option to the `ansible.cfg` file. - - {{< file "~/development/ansible.cfg">}} -[defaults] -host_key_checking = False -VAULT_PASSWORD_FILE = ~/development/vault-pass -inventory = /etc/hosts -[inventory] -enable_plugins = linode - {{}} - 1. Verify that you can communicate with your grouped inventory by pinging the Linodes. The ping command will use the dynamic inventory plugin configuration file to target `example_group`. The `u root` option will run the command as root on the Linode hosts. ansible -m ping example_group -i ~/development/linode.yml -u root From f813999a5478f606d9cc56786c5184142d6d1c50 Mon Sep 17 00:00:00 2001 From: Angel Date: Tue, 11 Jun 2019 14:19:30 -0400 Subject: [PATCH 9/9] Copy Edit --- .../deploy-linodes-using-ansible/index.md | 36 +++++++++---------- 1 file changed, 18 insertions(+), 18 deletions(-) diff --git a/docs/applications/configuration-management/deploy-linodes-using-ansible/index.md b/docs/applications/configuration-management/deploy-linodes-using-ansible/index.md index 76b05ba64d5..7a8080fcf1e 100644 --- a/docs/applications/configuration-management/deploy-linodes-using-ansible/index.md +++ b/docs/applications/configuration-management/deploy-linodes-using-ansible/index.md @@ -6,10 +6,10 @@ description: 'In this guide you learn how to deploy and manage Linodes using Ans keywords: ['ansible','Linode module','dynamic inventory','configuration management'] license: '[CC BY-ND 4.0](https://creativecommons.org/licenses/by-nd/4.0)' published: 2019-06-04 -modified: 2019-06-04 +modified: 2019-06-10 modified_by: name: Linode -title: "Deploy Linodes Using Ansible and the linode_v4 Module" +title: "How to use the Linode Ansible Module to Deploy Linodes" contributor: name: Linode external_resources: @@ -17,7 +17,7 @@ external_resources: --- Ansible is a popular open-source tool that can be used to automate common IT tasks, like cloud provisioning and configuration management. With [Ansible's 2.8 release](https://docs.ansible.com/ansible/latest/roadmap/ROADMAP_2_8.html), you can deploy Linode instances using our latest [API (v4)](https://developers.linode.com/api/v4/). Ansible's `linode_v4` module adds the functionality needed to deploy and manage Linodes via the command line or in your [Ansible Playbooks](/docs/applications/configuration-management/automatically-configure-servers-with-ansible-and-playbooks/). While the dynamic inventory plugin for Linode helps you source your Ansible inventory directly from the Linode API (v4). -In this guide you learn how to: +In this guide you will learn how to: * Deploy and manage Linodes using Ansible and the `linode_v4` module. * Create an Ansible inventory for your Linode infrastructure using the dynamic inventory plugin for Linode. @@ -25,7 +25,7 @@ In this guide you learn how to: {{< caution >}} This guide’s example instructions will create a [1 GB Nanode](https://www.linode.com/pricing) billable resource on your Linode account. If you do not want to keep using the Nanode that you create, be sure to [delete the resource](#delete-your-resources) when you have finished the guide. -If you remove the resources afterward, you will only be billed for the hour(s) that the resources were present on your account. +If you remove the resource afterward, you will only be billed for the hour(s) that the resources were present on your account. {{}} ## Before You Begin @@ -57,13 +57,13 @@ The Ansible configuration file is used to adjust Ansible's default system settin - `~/.ansible.cfg` in the home directory - `/etc/ansible/ansible.cfg` -In this section, you will create an Ansible configuration file and add options to disable host key checking and to whitelist the Linode inventory plugin. The Ansible configuration file will be located in a development directory that you create, however, it could exist in any of the locations listed above. See [Ansible's official documentation](https://docs.ansible.com/ansible/latest/reference_appendices/config.html#common-options) for a full list of available configuration settings. +In this section, you will create an Ansible configuration file and add options to disable host key checking, and to whitelist the Linode inventory plugin. The Ansible configuration file will be located in a development directory that you create, however, it could exist in any of the locations listed above. See [Ansible's official documentation](https://docs.ansible.com/ansible/latest/reference_appendices/config.html#common-options) for a full list of available configuration settings. {{< caution >}} When storing your Ansible configuration file, ensure that its corresponding directory does not have world-writable permissions. This could pose a security risk that allows malicious users to use Ansible to exploit your local system and remote infrastructure. At minimum, the directory should restrict access to particular users and groups. For example, you can create an `ansible` group, only add privileged users to the `ansible` group, and update the Ansible configuration file's directory to have `764` permissions. See the [Linux Users and Groups](/docs/tools-reference/linux-users-and-groups/) guide for more information on permissions. {{}} -1. In your home directory, create a directory to hold all your Ansible related files and move into the directory: +1. In your home directory, create a directory to hold all of your Ansible related files and move into the directory: mkdir development && cd development @@ -83,7 +83,7 @@ enable_plugins = linode ## Create a Linode Instance -You can now begin to create Linode instances using Ansible. In this section, you will create an Ansible Playbook that can deploy Linodes. +You can now begin creating Linode instances using Ansible. In this section, you will create an Ansible Playbook that can deploy Linodes. ### Create your Linode Playbook @@ -115,14 +115,14 @@ You can now begin to create Linode instances using Ansible. In this section, you {{}} - The Playbook `my_linode` contains the `Create Linode` play, which will be executed on `hosts: localhost`. This means the Ansible playbook will execute on the local system and use it as a vehicle to deploy the remote Linode instances. - - The `vars_files` key provides the location of a local file that contains variable values to populate in the play. The value of any variables defined in the vars file will substitute any Jinja template variables used in the Playbook. Jinja template variables are any vars between `{{ my_var }}`. + - The `vars_files` key provides the location of a local file that contains variable values to populate in the play. The value of any variables defined in the vars file will substitute any Jinja template variables used in the Playbook. Jinja template variables are any variables between curly brackets, like: `{{ my_var }}`. - The `Create a new Linode` task calls the `linode_v4` module and provides all required module parameters as arguments, plus additional arguments to configure the Linode's deployment. For details on each parameter, see the [linode_v4 Module Parameters](#linode-v4-module-parameters) section. {{< note >}} Usage of `groups` is deprecated, but still supported by Linode's API v4. The [Linode dynamic inventory module](#linode-dynamic-inventory-module) requires groups to generate an Ansible inventory and will be used later in this guide. {{}} - - The`register` keyword defines a variable name, `my_linode` that will store `linode_v4` module return data. For instance, you could reference the `my_linode` variable later in your Playbook to complete other actions using data about your Linode. This keyword is not required to deploy a Linode instance, but represents a common way to declare and use variables in Ansible Playbooks. For example, the task in the snippet below will use Ansible's [debug module](https://docs.ansible.com/ansible/2.4/debug_module.html) and the `my_linode` variable to print out a message with the Linode instance's ID and IPv4 address during Playbook execution. + - The`register` keyword defines a variable name, `my_linode` that will store `linode_v4` module return data. For instance, you could reference the `my_linode` variable later in your Playbook to complete other actions using data about your Linode. This keyword is not required to deploy a Linode instance, but represents a common way to declare and use variables in Ansible Playbooks. The task in the snippet below will use Ansible's [debug module](https://docs.ansible.com/ansible/2.4/debug_module.html) and the `my_linode` variable to print out a message with the Linode instance's ID and IPv4 address during Playbook execution. {{< file >}} ... @@ -133,7 +133,7 @@ You can now begin to create Linode instances using Ansible. In this section, you ### Create the Variables File -In the previous section, you created the Create Linode Playbook to deploy Linode instances and made use of Jinja template variables. In this section, you will create the variables file to provide values to those template variables. +In the previous section, you created the *Create Linode Playbook* to deploy Linode instances and made use of Jinja template variables. In this section, you will create the variables file to provide values to those template variables. 1. Create the directory to store your Playbook's variable files. The directory is structured to group your variable files by inventory group. This directory structure supports the use of file level encryption that Ansible Vault can detect and parse. Although it is not relevant to this guide's example, it will be used as a best practice. @@ -150,13 +150,13 @@ label: simple-linode- - The `ssh_keys` example passes a list of two public SSH keys. The first provides the string value of the key, while the second provides a local public key file location. {{< disclosure-note "Configure your SSH Agent" >}} -If your SSH Keys are passphrase-protected, you should add the keys to your SSH Agent so that Ansible does not hang when running Playbooks on the remote Linode. The following instructions are for Linux systems: +If your SSH Keys are passphrase-protected, you should add the keys to your SSH agent so that Ansible does not hang when running Playbooks on the remote Linode. The following instructions are for Linux systems: 1. Run the following command; if you stored your private key in another location, update the path that’s passed to ssh-add accordingly: eval $(ssh-agent) && ssh-add ~/.ssh/id_rsa - If you start a new terminal, you will need to run the commands in this step again before having access to the keys stored in your SSH Agent. + If you start a new terminal, you will need to run the commands in this step again before having access to the keys stored in your SSH agent. {{}} - `label` provides a label prefix that will be concatenated with a random number. This occurs when the Create Linode Playbook's Jinja templating for the `label` argument is parsed (`label: "{{ label }}{{ 100 |random }}"`). @@ -198,7 +198,7 @@ Encryption successful ansible-vault encrypt_string '86210...1e1c6bd' --name 'token' -1. Copy the generated output and it to the bottom of your `vars` file. +1. Copy the generated output and append it to the bottom of your `vars` file. The final `vars` file should resemble the example below: @@ -256,14 +256,14 @@ You are now ready to run the Create Linode Playbook. When you run the Playbook, | `image` | string | The Image ID to deploy the Linode disk from. Official Linode Images start with `linode/`, while your private images start with `private/`. For example, use `linode/ubuntu18.04` to deploy a Linode instance with the Ubuntu 18.04 image. This is a required parameter only when creating Linode instances.

To view a list of all available Linode images, issue the following command:

`curl https://api.linode.com/v4/images`.| | `label` | string, *required* | The Linode instance label. The label is used by the module as the main determiner for idempotence and must be a unique value.

Linode labels have the following constraints:

• Must start with an alpha character.
• May only consist of alphanumeric characters, dashes (-), underscores (_) or periods (.).
• Cannot have two dashes (--), underscores (__) or periods (..) in a row. | | `region` | string | The region where the Linode will be located. This is a required parameter only when creating Linode instances.

To view a list of all available regions, issue the following command:

`curl https://api.linode.com/v4/regions`. | -| `root_pass` | string | The password for the root user. If not specified, one will be generated. This generated password will be available in the task success JSON.

The root password must conform to the following constraints:

• May only use alphanumerics, punctuation, spaces, and tabs.
• Must contain at least two of the following characters classes: upper-case letters, lower-case letters, digits, punctuation. | +| `root_pass` | string | The password for the root user. If not specified, will be generated. This generated password will be available in the task success JSON.

The root password must conform to the following constraints:

• May only use alphanumerics, punctuation, spaces, and tabs.
• Must contain at least two of the following characters classes: upper-case letters, lower-case letters, digits, punctuation. | | `state` | string, *required* | The desired instance state. The accepted values are `absent` and `present`. | | `tags` | list | The user-defined labels attached to Linodes. Tags are used for grouping Linodes in a way that is relevant to the user. | | `type` | string, | The Linode instance's plan type. The plan type determines your Linode's [hardware resources](/docs/platform/how-to-choose-a-linode-plan/#hardware-resource-definitions) and its [pricing](https://www.linode.com/pricing#all).

To view a list of all available Linode types including pricing and specifications for each type, issue the following command:

`curl https://api.linode.com/v4/linode/types`. | ## The Linode Dynamic Inventory Plugin -Ansible uses *inventories* to manage different hosts that make up your infrastructure. This allows you to execute tasks on specific parts of your infrastructure. By default, Ansible will look in `/etc/ansible/hosts` for inventory, however, you can designate a different location for your inventory file and use multiple inventory files that represent your infrastructure. To support infrastructures that shift over time, Ansible offers the ability to track inventory from dynamic sources, like cloud providers. The Ansible dynamic inventory plugin for Linode can be used to source your inventory from Linode's API v4. In this section, you will use the Linode plugin to source your Ansible deployed Linode inventory. +Ansible uses *inventories* to manage different hosts that make up your infrastructure. This allows you to execute tasks on specific parts of your infrastructure. By default, Ansible will look in `/etc/ansible/hosts` for an inventory, however, you can designate a different location for your inventory file and use multiple inventory files that represent your infrastructure. To support infrastructures that shift over time, Ansible offers the ability to track inventory from dynamic sources, like cloud providers. The Ansible dynamic inventory plugin for Linode can be used to source your inventory from Linode's API v4. In this section, you will use the Linode plugin to source your Ansible deployed Linode inventory. {{< note >}} The dynamic inventory plugin for Linode was enabled in the Ansible configuration file created in the [Configure Ansible](#configure-ansible) section of this guide. @@ -308,9 +308,9 @@ types: 1. Before you can communicate with your Linode instances using the dynamic inventory plugin, you will need to add your Linode's IPv4 address and label to your `/etc/hosts` file. The Linode Dynamic Inventory Plugin assumes that the Linodes in your account have labels that correspond to hostnames that are in your resolver search path, `/etc/hosts`. This means you will have to create an entry in your `/etc/hosts` file to map the Linode's IPv4 address to its hostname. - - A [pull request](https://github.com/ansible/ansible/pull/51196) currently exists to support using a public IP, private IP or hostname. This change will enable the inventory plugin to be used with infrastructure that does not have DNS hostnames or hostnames that match Linode labels. - + {{< note >}} +A [pull request](https://github.com/ansible/ansible/pull/51196) currently exists to support using a public IP, private IP or hostname. This change will enable the inventory plugin to be used with infrastructure that does not have DNS hostnames or hostnames that match Linode labels. +{{}} To add your deployed Linode instance to the `/etc/hosts` file: - Retrieve your Linode instance's IPv4 address: