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 38 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.
+179 −186
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,5 +1,5 @@
Getting Started with Docker
===========================
Docker 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 @@
Getting Started with Kubernetes and OpenShift
=============================================
Kubernetes and OpenShift 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,6 +1,6 @@
*************************
Using Ansible with Online
*************************
****************
Online.net Guide
****************

Introduction
============
@@ -1,8 +1,8 @@
.. _guide_scaleway:

***************************
Using Scaleway with Ansible
***************************
**************
Scaleway Guide
**************

.. _scaleway_introduction:

@@ -1,5 +1,5 @@
Using Vagrant and Ansible
=========================
Vagrant Guide
=============

.. _vagrant_intro:

@@ -151,4 +151,3 @@ The "Tips and Tricks" chapter of the `Ansible Provisioner documentation
The open issues for the Ansible provisioner in the Vagrant project
:ref:`working_with_playbooks`
An introduction to playbooks

@@ -0,0 +1,30 @@
.. _vmware_ansible:

******************
VMware Guide
******************

Welcome to the Ansible for VMware Guide!

The purpose of this guide is to teach you everything you need to know about using Ansible with VMware.

To get started, please select one of the following topics.

.. toctree::
:maxdepth: 1

vmware_scenarios/vmware_intro
This conversation was marked as resolved by acozine

This comment has been minimized.

Copy link
@gundalow

gundalow Mar 13, 2019

Contributor

Is this a case where vmware_scenarios/* would work, or are you wanting to define a specific order?

This comment has been minimized.

Copy link
@samccann

samccann Mar 13, 2019

Contributor

needs to be a specific order imo...otherwise vmware_concepts would come before vmware_intro, wouldn't it?

This comment has been minimized.

Copy link
@acozine

acozine Mar 19, 2019

Author Contributor

Yep, I was going for a specific order. We could use a blob TOC with vmware_scenarios/* if we renamed the scenarios to start with numbers: 1_intro, then 2_next thing, etc., but I think that kind of ruins the usefulness of the blob approach - contributors would have to understand and follow the naming convention for that to work.

vmware_scenarios/vmware_concepts
vmware_scenarios/vmware_requirements
vmware_scenarios/vmware_inventory
vmware_scenarios/vmware_scenarios
vmware_scenarios/vmware_troubleshooting
vmware_scenarios/vmware_external_doc_links
vmware_scenarios/faq
.. comments look like this - start with two dots
.. getting_started content not ready
.. vmware_scenarios/vmware_getting_started
.. module index page not ready
.. vmware_scenarios/vmware_module_reference
.. always exclude the template file
.. vmware_scenarios/vmware_scenario_1

This file was deleted.

Oops, something went wrong.
@@ -0,0 +1,40 @@
.. _integration_guides:

******************
Integration Guides
******************

The guides in this section cover integrating Ansible with a variety of
platforms, products, and technologies. They explore particular use cases in greater depth and provide a more "top-down" explanation of some basic features.

.. toctree::
:maxdepth: 1
:caption: Cloud Integration Guides

guide_alicloud
guide_aws
guide_azure
guide_cloudstack
guide_gce
guide_online
guide_packet
guide_rax
guide_scaleway
guide_vultr

.. toctree::
:maxdepth: 1
:caption: Network Integration Guides

This comment has been minimized.

Copy link
@gundalow

gundalow Mar 13, 2019

Contributor

Does the main network index page want to be linked here?

This comment has been minimized.

Copy link
@samccann

samccann Mar 13, 2019

Contributor

If you mean moving the main network index page to be under this Integrations sections, no. Network automatin has to stay at the highest level to remain visible. If you mean should we have a separate link somewhere on the 'network integrations guide' section to point to the network main guides..possibly yeah.

This comment has been minimized.

Copy link
@gundalow

gundalow Mar 15, 2019

Contributor

Sorry, I want clear. Would it be worth adding a link to the network guides (which shouldn't move)

This comment has been minimized.

Copy link
@acozine

acozine Mar 21, 2019

Author Contributor

I am in favor of the idea - generally the easier it is for a user to get to the content she needs/wants, the better, so linking between related but different content is a good idea. I'm not sure of the best way to add a link to a TOC page, but I will experiment with options.

guide_aci
guide_meraki
guide_infoblox

.. toctree::
:maxdepth: 1
:caption: Virtualization & Containerization Integration Guides

guide_docker
guide_kubernetes
guide_vagrant
guide_vmware
@@ -4,9 +4,10 @@
Ansible for VMware Concepts
***************************

These concepts are common to all uses of Ansible, including VMware automation. You need to understand them to use Ansible for VMware automation. This basic introduction provides the background you need to follow the examples in this guide.
Some of these concepts are common to all uses of Ansible, including VMware automation; some are specific to VMware. You need to understand them to use Ansible for VMware automation. This introduction provides the background you need to follow the :ref:`scenarios<vmware_scenarios>` in this guide.

.. contents:: Topics
.. contents::
:local:

Control Node
============
@@ -16,20 +17,18 @@ Any machine with Ansible installed. You can run commands and playbooks, invoking
Delegation
==========

If you want to perform a VMware specific task on one host with reference to ESXi server or vCenter server, use the ``delegate_to`` keyword on a task. This delegation host will be any host where you have ``pyVmomi`` installed. Your control node and ``delegate_to`` host can be same or different.
Delegation allows you to select the system that executes a given task. If you do not have ``pyVmomi`` installed on your control node, use the ``delegate_to`` keyword on VMware-specific tasks to execute them on any host where you have ``pyVmomi`` installed.

Modules
=======

The units of code Ansible executes. Each module has a particular use, from creating virtual machines on vCenter to managing distributed virtual switches on vCenter environment. You can invoke a single module with a task, or invoke several different modules in a playbook. For an idea of how many modules Ansible includes, take a look at the :ref:`list of VMware modules<vmware_cloud_modules>`.

The units of code Ansible executes. Each module has a particular use, from creating virtual machines on vCenter to managing distributed virtual switches in the vCenter environment. You can invoke a single module with a task, or invoke several different modules in a playbook. For an idea of how many modules Ansible includes, take a look at the :ref:`list of cloud modules<cloud_modules>`, which includes VMware modules.

Playbooks
=========

Ordered lists of tasks, saved so you can run those tasks in that order repeatedly. Playbooks can include variables as well as tasks. Playbooks are written in YAML and are easy to read, write, share and understand.


pyVmomi
=======

@@ -1,10 +1,8 @@
.. _vmware_external_doc_links:

******************************
List of useful links to VMware
******************************

Following is the list of various external documentation and guides which can helpful in further readings.
*****************************
Other useful VMware resources
*****************************

* `PyVmomi Documentation <https://github.com/vmware/pyvmomi/tree/master/docs>`_
* `VMware API and SDK Documentation <https://www.vmware.com/support/pubs/sdk_pubs.html>`_
@@ -1,3 +1,5 @@
:orphan:

.. _vmware_ansible_getting_started:

***************************************
@@ -1,7 +1,9 @@
:orphan:

.. _vmware_ansible_module_index:

***************************
Ansible VMware Module Guide
***************************

This will be a listing similar to the module index in our core docs.
This will be a listing similar to the module index in our core docs.
@@ -4,28 +4,22 @@
VMware Prerequisites
********************

.. contents:: Topics
.. contents::
:local:

Installing SSL Certificates
===========================

Installing SSL Certificate
==========================
All vCenter and ESXi servers require SSL encryption on all connections to enforce secure communication. You must enable SSL encryption for Ansible by installing the server's SSL certificates on your Ansible control node or delegate node.

All vCenter and ESXi servers require SSL encryption on all connections to enforce secure communication.
If the SSL certificate of your vCenter or ESXi server is not correctly installed on your Ansible control node, you will see the following warning when using Ansible VMware modules:

If you see the following warning while using Ansible VMware modules [warning], you need to enable SSL encryption for Ansible by installing the server's SSL certificates on your Ansible control node or delegate node.
``Unable to connect to vCenter or ESXi API at xx.xx.xx.xx on TCP/443: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed (_ssl.c:777)``

```
Unable to connect to vCenter or ESXi API at xx.xx.xx.xx on TCP/443: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed (_ssl.c:777)
```
To install the SSL certificate for your VMware server, and run your Ansible VMware modules in encrypted mode, please follow the instructions for the server you are running with VMware.

then, this means you need to add/install SSL certificate of vCenter or ESXi server in your Ansible control node.

The following instructions allow you to run your Ansible VMware modules with encrypted mode (viz. ``validate_certs=True``).

Please follow the instructions depending upon your server to install SSL certificate.

vCenter
-------
Installing vCenter SSL certificates for Ansible
-----------------------------------------------

* From any web browser, go to the base URL of the vCenter Server without port number like ``https://vcenter-domain.example.com``

@@ -38,9 +32,8 @@ vCenter
* Install the certificate files are trusted certificates by the process that is appropriate for your operating system.



ESXi
----
Installing ESXi SSL certificates for Ansible
--------------------------------------------

* Enable SSH Service on ESXi either by using Ansible VMware module `vmware_host_service_manager <https://github.com/ansible/ansible/blob/devel/lib/ansible/modules/cloud/vmware/vmware_host_config_manager.py>`_ or manually using vSphere Web interface.

@@ -1,4 +1,4 @@
.. _vmware_scenario_1:
:orphan:

**********************************
Sample Scenario for Ansible VMware
@@ -4,21 +4,13 @@
Ansible for VMware Scenarios
****************************

Welcome to the Ansible for VMWare Guide!

The purpose of this guide is to teach you everything you need to know about using Ansible with VMWare.

To get started, please select one of the following topics.

These scenarios teach you how to accomplish common VMware tasks using Ansible. To get started, please select the task you want to accomplish.

.. toctree::
:maxdepth: 2
:maxdepth: 1

scenario_clone_template
scenario_rename_vm
scenario_remove_vm
scenario_find_vm_folder
scenario_vmware_http
vmware_scenario_1


@@ -8,8 +8,8 @@ Troubleshooting Ansible for VMware

This section lists things that can go wrong and possible ways to fix them.

Debugging
=========
Debugging Ansible for VMware
============================

When debugging or creating a new issue, you will need information about your VMware infrastructure. You can get this information using
`govc <https://github.com/vmware/govmomi/tree/master/govc>`_, For example:
@@ -22,8 +22,8 @@ When debugging or creating a new issue, you will need information about your VMw
$ export GOVC_URL=https://ESXI_OR_VCENTER_HOSTNAME:443
$ govc find /
Known issues
============
Known issues with Ansible for VMware
====================================


Network settings with vmware_guest in Ubuntu 18.04
@@ -35,15 +35,15 @@ This issue is tracked via:
* https://github.com/vmware/open-vm-tools/issues/240
* https://github.com/ansible/ansible/issues/41133

Potential Workaround
^^^^^^^^^^^^^^^^^^^^
Potential Workarounds
^^^^^^^^^^^^^^^^^^^^^

There are several workarounds for this issue.

1) Modifying the Ubuntu 18.04 images and installing ``ifupdown`` in them via ``sudo apt install ifupdown``.
1) Modify the Ubuntu 18.04 images and installing ``ifupdown`` in them via ``sudo apt install ifupdown``.
If so you need to remove ``netplan`` via ``sudo apt remove netplan.io`` and you need stop ``systemd-networkd`` via ``sudo systemctl disable systemctl-networkd``.

2) You can generate the ``systemd-networkd`` files with a task in your vmware Ansible role:
2) Generate the ``systemd-networkd`` files with a task in your VMware Ansible role:

.. code-block:: yaml
@@ -100,14 +100,3 @@ There are several workarounds for this issue.
delegate_to: localhost
3) Wait for ``netplan`` support in ``open-vm-tools``


Troubleshooting Item
====================

Description

Potential Workaround
--------------------

How to fix...
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.