Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

WIP: DOCS - shorten Scenario Guides, incorporate VMware Guide #53569

Closed
wants to merge 44 commits into from
Closed
Changes from 36 commits
Commits
Show all changes
44 commits
Select commit Hold shift + click to select a range
dcb8e8c
changes TOC to Integration Guides
acozine Feb 27, 2019
3eb80f0
updates index page for integration guides
acozine Feb 27, 2019
efdd290
renames guides.rst to integration_guides.rst to match anchor
acozine Feb 27, 2019
f59e3e3
rename all guides to /Product Guide
acozine Feb 27, 2019
b0962e5
copies vmware guide index page to scenario guides section
acozine Feb 27, 2019
d8bbd40
adds sub-pages for vmware guide into sub-dir
acozine Feb 27, 2019
ce55e47
first attempt to sort out the internal vmware guide's TOC
acozine Feb 27, 2019
a4833d3
updates main index for renamed guides index
acozine Feb 27, 2019
331a50b
change caption for integration guides section
acozine Feb 27, 2019
022d937
Change title of VMware index page
acozine Feb 27, 2019
65602fc
change title of k8s guide
acozine Feb 27, 2019
c48774a
trying to makes sense of the TOC
acozine Mar 7, 2019
67cf0d9
this file belongs here, I think
acozine Mar 7, 2019
2f18305
does this make the local TOC appear?
acozine Mar 8, 2019
3d4a060
oh right, toctree not contents
acozine Mar 8, 2019
561096b
d'oh, relative path mistake
acozine Mar 8, 2019
4ccf2c4
remove duplicate intro TOC entry
acozine Mar 8, 2019
0bb529c
update concepts page, esp. delegation
acozine Mar 8, 2019
ffcf563
updates vmware prereqs page
acozine Mar 8, 2019
064726a
updates vmware troubleshooting page
acozine Mar 8, 2019
938b489
sanding 'module' entry on vmware concepts
acozine Mar 8, 2019
37d002b
removes incomplete content from TOC
acozine Mar 8, 2019
5ae0fc9
clean up external links page
acozine Mar 8, 2019
94d73ea
oh right, rst comments don't start with #
acozine Mar 8, 2019
ccb65bf
no index page for VMware modules, link to cloud instead
acozine Mar 8, 2019
aa88a50
comments can't interrupt the toctree
acozine Mar 8, 2019
ebded63
removes vmware docs diretory
acozine Mar 8, 2019
330dd18
removes vmware section from main TOC
acozine Mar 8, 2019
70a9043
incorporate latest changes to vmware_inventory file
acozine Mar 8, 2019
c2616d1
clarify commented-out items on vmware guide toc
acozine Mar 11, 2019
1b3165f
make unused pages orphans
acozine Mar 11, 2019
342274b
moves and updates rolling upgrade guide
acozine Mar 11, 2019
3ea55e9
incorporates rolling upgrade guide in its new location
acozine Mar 11, 2019
5363827
categorize integration guides
acozine Mar 12, 2019
af9421c
alphabetize guides by title
acozine Mar 12, 2019
994c8a0
inserts Ansible into all guide titles
acozine Mar 12, 2019
21197b3
add cloudstack guide to toctree
acozine Mar 14, 2019
e6d9d53
Revert "inserts Ansible into all guide titles"
acozine Mar 14, 2019
d2767c5
New caption and title, rename index for section
acozine Mar 21, 2019
ba25649
going back to Scenario Guides
acozine Mar 21, 2019
fab4d8b
alphabetize Azure as Microsoft Azure
acozine Mar 21, 2019
dfdf5a7
separates 3 types of scenario guides
acozine Mar 21, 2019
de3198a
orphans old index page
acozine Mar 21, 2019
77d0dea
adds blank line per CI
acozine Mar 21, 2019
File filter...
Filter file types
Jump to…
Jump to file or symbol
Failed to load files and symbols.
+246 −259
Diff settings

Always

Just for now

Copy path View file
@@ -47,16 +47,10 @@ Ansible releases a new major release of Ansible approximately three to four time

.. toctree::
:glob:
:maxdepth: 2
:caption: Scenario Guides

scenario_guides/guide_*

.. toctree::
:maxdepth: 2
:caption: Ansible for VMWare
:maxdepth: 1
:caption: Integrating Ansible with Other Tools

This comment has been minimized.

Copy link
@dagwieers

dagwieers Mar 14, 2019

Member

I read this as Modifying Ansible to work together with other tools which is not what this content is about.

These Scenario Guides describe for different technologies (or infrastructure) how to best automate or manage that infrastructure/product.

"Tools" here is also a misnomer IMO, Ansible is a tool, but your production database is not a tool.

integrate verb
combine (one thing) with another to form a whole.
"transport planning should be integrated with energy policy"
synonyms: combine, amalgamate, merge, unite, join, fuse, blend, mingle, coalesce, consolidate, meld, intermingle, mix, intermix, incorporate, affiliate, unify, assimilate, homogenize, harmonize, mesh, desegregate; literarycommingle
"he proposes to integrate our reserve forces more closely with the regular forces"

Not sure what I have to do to get this point across...

This comment has been minimized.

Copy link
@acozine

acozine Mar 19, 2019

Author Contributor

@dagwieers it's still a WIP, and your point is well taken. I searched for a term that describes all the technologies covered in this section of the docs. The word "tool" is not my favorite, but was the best catch-all term I had come up with so far.

The Scenario Guides are too numerous to appear in the left-nav. Right now with Scenario Guides as the caption and the various Guide titles below, the user can get the idea pretty easily.
If we collapse the TOC and keep the name Scenario Guides, what can we use as the Caption above it? The other sections start a pattern:
Using Ansible: User Guide
and
Contributing to Ansible: Community Guide
So what would work for the Scenario Guides section?
Managing Technology with Ansible: Scenario Guides?

This comment has been minimized.

Copy link
@dagwieers

dagwieers Mar 19, 2019

Member

If the Scenario Guides cannot be at the left in full, that's fine, but I don't see what changing the name fixes. Unless we have a better name that is.

Scenario Guides
Automate and manage other technologies with Ansible

Although I think I like Automation Guides better now, but that's just a personal preference. It does allow to remove the "Automate" part from the description.

Automation guides
Manage other technologies with Ansible

This comment has been minimized.

Copy link
@acozine

acozine Mar 21, 2019

Author Contributor

I think we can leave automation out anyway - if it's Ansible, it's automation by definition.


vmware/index
scenario_guides/integration_guides.rst

.. toctree::
:maxdepth: 2
@@ -1,7 +1,7 @@
.. _aci_guide:

Cisco ACI Guide
===============
Cisco ACI Ansible Guide
This conversation was marked as resolved by dagwieers

This comment has been minimized.

Copy link
@dagwieers

dagwieers Mar 12, 2019

Member

I am not in favor of this.

It is stored on docs.ansible.com, it has Ansible in large at the top, the page title already is "Cisco ACI Guide — Ansible Documentation", so there is absolutely no need to add it again in (every guide's) title IMO.

This comment has been minimized.

Copy link
@acozine

acozine Mar 13, 2019

Author Contributor

This was a recommendation from our SEO expert to improve indexing and make the guides easy to find.

This comment has been minimized.

Copy link
@dagwieers

dagwieers Mar 13, 2019

Member

Searching for Ansible and ACI makes it the first hit. Ansible is already in the title once and in the domain. You cannot make it better than that.

=======================


.. _aci_guide_intro:
@@ -60,7 +60,7 @@ For instance ensuring that a specific tenant exists, is done using the following
host: my-apic-1
username: admin
password: my-password
This conversation was marked as resolved by dagwieers

This comment has been minimized.

Copy link
@dagwieers

dagwieers Mar 12, 2019

Member

This was done on purpose, the block example continues.
It's one single example, not two paragraphs.
The only reason to not remove that line is because in these examples we want to separate the connection-part from the actual module parameters.

This comment has been minimized.

Copy link
@acozine

acozine Mar 13, 2019

Author Contributor

hm, not sure where that change came from - I didn't mean to change anything in the guides themselves except for the titles

This comment has been minimized.

Copy link
@dagwieers

dagwieers Mar 13, 2019

Member

No worries, most likely your editor is removing trailing spaces, which is mostly a good thing ;-)

tenant: customer-xyz
description: Customer XYZ
state: present
@@ -81,7 +81,7 @@ A module can also be used to query a specific object.
host: my-apic-1
username: admin
password: my-password
tenant: customer-xyz
state: query
register: my_tenant
@@ -95,7 +95,7 @@ Or query all objects.
host: my-apic-1
username: admin
password: my-password
state: query
register: all_tenants
@@ -147,7 +147,7 @@ One way to set this up is to add to every task the directive: ``delegate_to: loc
host: '{{ ansible_host }}'
username: '{{ ansible_user }}'
password: '{{ ansible_password }}'
state: query
delegate_to: localhost
register: all_tenants
@@ -180,7 +180,7 @@ But used tasks do not need anything special added.
host: '{{ ansible_host }}'
username: '{{ ansible_user }}'
password: '{{ ansible_password }}'
state: query
register: all_tenants
@@ -348,7 +348,7 @@ You can automate this by using the following Ansible task:
host: my-apic-1
username: admin
password: my-password
aaa_user: admin
certificate_name: admin
certificate: "{{ lookup('file', 'pki/admin.crt') }}" # This will read the certificate data from a local file
@@ -403,7 +403,7 @@ For instance, if you would like to ensure a specific tenant exists on ACI, these
- aci_rest:
host: my-apic-1
private_key: pki/admin.key
method: post
path: /api/mo/uni.xml
content: |
@@ -416,7 +416,7 @@ For instance, if you would like to ensure a specific tenant exists on ACI, these
- aci_rest:
host: my-apic-1
private_key: pki/admin.key
method: post
path: /api/mo/uni.json
content:
@@ -436,7 +436,7 @@ For instance, if you would like to ensure a specific tenant exists on ACI, these
- aci_rest:
host: my-apic-1
private_key: pki/admin.key
method: post
path: /api/mo/uni.json
content:
@@ -452,7 +452,7 @@ For instance, if you would like to ensure a specific tenant exists on ACI, these
- aci_tenant:
host: my-apic-1
private_key: pki/admin.key
tenant: customer-xyz
description: Customer XYZ
state: present
@@ -1,5 +1,5 @@
Alibaba Cloud Compute Services Guide
====================================
Alibaba Cloud Compute Services Ansible Guide
============================================

.. _alicloud_intro:

@@ -26,7 +26,7 @@ Normally, you'll use the following pattern for plays that provision Alicloud res

Authentication
``````````````

You can specify your Alicloud authentication credentials (access key and secret key) by passing them as
environment variables or by storing them in a vars file.

@@ -1,5 +1,5 @@
Amazon Web Services Guide
=========================
Amazon Web Services Ansible Guide
=================================

.. _aws_intro:

@@ -9,7 +9,7 @@ Introduction
Ansible contains a number of modules for controlling Amazon Web Services (AWS). The purpose of this
section is to explain how to put Ansible modules together (and use inventory scripts) to use Ansible in AWS context.

Requirements for the AWS modules are minimal.
Requirements for the AWS modules are minimal.

All of the modules require and are tested against recent versions of boto. You'll need this Python module installed on your control machine. Boto can be installed from your OS distribution or python's "pip install boto".

@@ -27,8 +27,8 @@ In your playbook steps we'll typically be using the following pattern for provis

Authentication
``````````````
Authentication with the AWS-related modules is handled by either

Authentication with the AWS-related modules is handled by either
specifying your access and secret key as ENV variables or module arguments.

For environment variables::
@@ -54,9 +54,9 @@ Note that if you store your credentials in vars_file, you need to refer to them
Provisioning
````````````

The ec2 module provisions and de-provisions instances within EC2.
The ec2 module provisions and de-provisions instances within EC2.

An example of making sure there are only 5 instances tagged 'Demo' in EC2 follows.
An example of making sure there are only 5 instances tagged 'Demo' in EC2 follows.

In the example below, the "exact_count" of instances is set to 5. This means if there are 0 instances already existing, then
5 new instances would be created. If there were 2 instances, only 3 would be created, and if there were 8 instances, 3 instances would
@@ -74,12 +74,12 @@ instance.::
tasks:

- name: Provision a set of instances
ec2:
ec2:
key_name: my_key
group: test
instance_type: t2.micro
image: "{{ ami_id }}"
wait: true
wait: true
exact_count: 5
count_tag:
Name: Demo
@@ -100,19 +100,19 @@ From this, we'll use the add_host module to dynamically create a host group cons
tasks:

- name: Provision a set of instances
ec2:
ec2:
key_name: my_key
group: test
instance_type: t2.micro
image: "{{ ami_id }}"
wait: true
wait: true
exact_count: 5
count_tag:
Name: Demo
instance_tags:
Name: Demo
register: ec2

- name: Add all instance public IPs to host group
add_host: hostname={{ item.public_ip }} groups=ec2hosts
loop: "{{ ec2.instances }}"
@@ -141,7 +141,7 @@ Host Inventory
``````````````

Once your nodes are spun up, you'll probably want to talk to them again. With a cloud setup, it's best to not maintain a static list of cloud hostnames
in text files. Rather, the best way to handle this is to use the ec2 dynamic inventory script. See :ref:`dynamic_inventory`.
in text files. Rather, the best way to handle this is to use the ec2 dynamic inventory script. See :ref:`dynamic_inventory`.

This will also dynamically select nodes that were even created outside of Ansible, and allow Ansible to manage them.

@@ -176,9 +176,9 @@ Autoscaling with Ansible Pull
Amazon Autoscaling features automatically increase or decrease capacity based on load. There are also Ansible modules shown in the cloud documentation that
can configure autoscaling policy.

When nodes come online, it may not be sufficient to wait for the next cycle of an ansible command to come along and configure that node.
When nodes come online, it may not be sufficient to wait for the next cycle of an ansible command to come along and configure that node.

To do this, pre-bake machine images which contain the necessary ansible-pull invocation. Ansible-pull is a command line tool that fetches a playbook from a git server and runs it locally.
To do this, pre-bake machine images which contain the necessary ansible-pull invocation. Ansible-pull is a command line tool that fetches a playbook from a git server and runs it locally.

One of the challenges of this approach is that there needs to be a centralized way to store data about the results of pull commands in an autoscaling context.
For this reason, the autoscaling solution provided below in the next section can be a better approach.
@@ -202,7 +202,7 @@ with remote hosts.
Ansible With (And Versus) CloudFormation
````````````````````````````````````````

CloudFormation is a Amazon technology for defining a cloud stack as a JSON or YAML document.
CloudFormation is a Amazon technology for defining a cloud stack as a JSON or YAML document.

Ansible modules provide an easier to use interface than CloudFormation in many examples, without defining a complex JSON/YAML document.
This is recommended for most users.
@@ -223,7 +223,7 @@ AWS Image Building With Ansible
Many users may want to have images boot to a more complete configuration rather than configuring them entirely after instantiation. To do this,
one of many programs can be used with Ansible playbooks to define and upload a base image, which will then get its own AMI ID for usage with
the ec2 module or other Ansible AWS modules such as ec2_asg or the cloudformation module. Possible tools include Packer, aminator, and Ansible's
ec2_ami module.
ec2_ami module.

Generally speaking, we find most users using Packer.

@@ -251,4 +251,3 @@ documentation for a full list with examples.
Have a question? Stop by the google group!
`irc.freenode.net <http://irc.freenode.net>`_
#ansible IRC chat channel

@@ -1,5 +1,5 @@
Microsoft Azure Guide
=====================
Microsoft Azure Ansible Guide
=============================

Ansible includes a suite of modules for interacting with Azure Resource Manager, giving you the tools to easily create
and orchestrate infrastructure on the Microsoft Azure Cloud.
@@ -1,5 +1,5 @@
CloudStack Cloud Guide
======================
CloudStack Cloud Ansible Guide
==============================

.. _cloudstack_introduction:

@@ -1,5 +1,5 @@
Getting Started with Docker
===========================
Docker Ansible Guide
====================

Ansible offers the following modules for orchestrating Docker containers:

@@ -327,7 +327,3 @@ For the default host and each host in the hosts list define the following attrib
description: The port containers use for SSH
required: false
default: 22
@@ -1,5 +1,5 @@
Google Cloud Platform Guide
===========================
Google Cloud Platform Ansible Guide
===================================

.. gce_intro:
@@ -29,7 +29,7 @@ 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
community has a great experience with GCP and therefore recommends adopting
these new modules if possible.

@@ -42,7 +42,7 @@ The Google Cloud Platform (GCP) modules require both the ``requests`` and the
$ pip install requests google-auth
Alternatively for RHEL / CentOS, the ``python-requests`` package is also
Alternatively for RHEL / CentOS, the ``python-requests`` package is also
available to satisfy ``requests`` libraries.

.. code-block:: bash
@@ -1,7 +1,7 @@
.. _nios_guide:

************************
Infoblox Guide
Infoblox Ansible Guide
************************

.. contents:: Topics
@@ -1,5 +1,5 @@
Getting Started with Kubernetes and OpenShift
=============================================
Kubernetes and OpenShift Ansible Guide
======================================

Modules for interacting with the Kubernetes (K8s) and OpenShift API are under development, and can be used in preview mode. To use them, review the requirements, and then follow the installation and use instructions.

@@ -53,4 +53,3 @@ Filing issues
If you find a bug or have a suggestion regarding individual modules or the role, please file issues at `OpenShift Rest Client issues <https://github.com/openshift/openshift-restclient-python/issues>`_.

There is also a utility module, k8s_common.py, that is part of the `Ansible <https://github.com/ansible/ansible>`_ repo. If you find a bug or have suggestions regarding it, please file issues at `Ansible issues <https://github.com/ansible/ansible/issues>`_.

@@ -1,8 +1,8 @@
.. _meraki_guide:

******************
Cisco Meraki Guide
******************
**************************
Cisco Meraki Ansible Guide
**************************

.. contents::
:local:
@@ -90,7 +90,7 @@ These are the common parameters which are used for most every module.
state
General specification of what action to take. ``query`` does lookups. ``present`` creates or edits. ``absent`` deletes.

.. hint:: Use the ``org_id`` and ``net_id`` parameters when possible. ``org_name`` and ``net_name`` require additional behind-the-scenes API calls to learn the ID values. ``org_id`` and ``net_id`` will perform faster.
.. hint:: Use the ``org_id`` and ``net_id`` parameters when possible. ``org_name`` and ``net_name`` require additional behind-the-scenes API calls to learn the ID values. ``org_id`` and ``net_id`` will perform faster.

Meraki Authentication
=====================
@@ -110,7 +110,7 @@ Meraki and its related Ansible modules return most information in the form of a
[
{
"orgAccess": "full",
"orgAccess": "full",
"name": "John Doe",
"tags": [],
"networks": [],
@@ -153,7 +153,7 @@ Ansible's Meraki modules do not allow for manipulating data. For example, you ma

- set_fact:
new_rule:
-
-
- comment: Block traffic to server
src_cidr: 192.0.1.0/24
src_port: any
@@ -1,6 +1,6 @@
*************************
Using Ansible with Online
*************************
************************
Online.net Ansible Guide
************************

Introduction
============
@@ -1,5 +1,5 @@
**********************************
Packet.net Guide
Packet.net Ansible Guide
**********************************

Introduction
Oops, something went wrong.
ProTip! Use n and p to navigate between commits in a pull request.
You can’t perform that action at this time.