Added guidance on using credentials in a playbook (#804) (#806)

Added information, restructured assembly

Transfer KCS information to Controller User Guide

https://issues.redhat.com/browse/AAP-18440

downstream/assemblies/platform/assembly-controller-credentials.adoc

@@ -33,6 +33,35 @@ If passwords are used, {ControllerName} handles those by responding directly to
 include::platform/ref-controller-credentials-getting-started.adoc[leveloffset=+1]
 include::platform/proc-controller-create-credential.adoc[leveloffset=+1]
 include::platform/ref-controller-credential-types.adoc[leveloffset=+1]
+include::platform/ref-controller-credential-aws.adoc[leveloffset=+2]
+include::platform/ref-controller-credential-galaxy-hub.adoc[leveloffset=+2]
+include::platform/ref-controller-credential-centrify-vault.adoc[leveloffset=+2]
+include::platform/ref-controller-credential-container-registry.adoc[leveloffset=+2]
+include::platform/ref-controller-credential-cyberark-central.adoc[leveloffset=+2]
+include::platform/ref-controller-credential-cyberark-conjur.adoc[leveloffset=+2]
+include::platform/ref-controller-credential-gitHub-pat.adoc[leveloffset=+2]
+include::platform/ref-controller-credential-gitLab-pat.adoc[leveloffset=+2]
+include::platform/ref-controller-credential-GCE.adoc[leveloffset=+2]
+include::platform/ref-controller-credential-GPG-public-key.adoc[leveloffset=+2]
+include::platform/ref-controller-credential-hashiCorp-secret.adoc[leveloffset=+2]
+include::platform/ref-controller-credential-hashiCorp-vault.adoc[leveloffset=+2]
+include::platform/ref-controller-credential-insights.adoc[leveloffset=+2]
+include::platform/ref-controller-credential-machine.adoc[leveloffset=+2]
+include::platform/ref-controller-credential-azure-key.adoc[leveloffset=+2]
+include::platform/ref-controller-credential-azure-resource.adoc[leveloffset=+2]
+include::platform/ref-controller-credential-network.adoc[leveloffset=+2]
+include::platform/ref-controller-credential-openShift.adoc[leveloffset=+2]
+include::platform/proc-controller-credential-create-openshift-account.adoc[leveloffset=+3]
+include::platform/ref-controller-credential-openStack.adoc[leveloffset=+2]
+include::platform/ref-controller-credential-aap.adoc[leveloffset=+2]
+include::platform/ref-controller-credential-satellite.adoc[leveloffset=+2]
+include::platform/ref-controller-credential-virtualization.adoc[leveloffset=+2]
+include::platform/ref-controller-credential-source-control.adoc[leveloffset=+2]
+include::platform/ref-controller-credential-thycotic-vault.adoc[leveloffset=+2]
+include::platform/ref-controller-credential-thycotic-server.adoc[leveloffset=+2]
+include::platform/ref-controller-credential-vault.adoc[leveloffset=+2]
+include::platform/ref-controller-credential-vmware-vcenter.adoc[leveloffset=+2]
+include::platform/ref-controller-use-credentials-in-playbooks.adoc[leveloffset=+1]
 
 endif::controller-UG[]
 

downstream/modules/platform/ref-controller-credential-GCE.adoc

@@ -25,3 +25,16 @@ GCE credentials require the following inputs:
 Click btn:[Browse] to browse for the file that contains the special account information that can be used by services and applications running on your GCE instance to interact with other Google Cloud Platform APIs.
 This grants permissions to the service account and virtual machine instances.
 * *RSA Private Key*: The PEM file associated with the service account email.
+
+== Access Google Compute Engine credentials in an ansible playbook
+
+You can get GCE credential parameters from a job runtime environment:
+
+[literal, options="nowrap" subs="+attributes"]
+----
+vars:
+  gce:
+    email: '{{ lookup("env", "GCE_EMAIL") }}'
+    project: '{{ lookup("env", "GCE_PROJECT") }}'
+    pem_file_path: '{{ lookup("env", "GCE_PEM_FILE_PATH") }}'
+----

downstream/modules/platform/ref-controller-credential-aap.adoc

@@ -12,3 +12,16 @@ Select this credential to access another {ControllerName} instance.
 * *Username*: The username to use to connect to it.
 * *Password*: The password to use to connect to it.
 * *Oauth Token*: If username and password are not used, provide an OAuth token to use to authenticate.
+
+== Access {ControllerName} credentials in an ansible playbook
+
+You can get the host, username, and password parameters from a job runtime environment:
+
+[literal, options="nowrap" subs="+attributes"]
+----
+vars:
+  controller:
+    host: '{{ lookup("env", "CONTROLLER_HOST") }}'
+    username: '{{ lookup("env", "CONTROLLER_USERNAME") }}'
+    password: '{{ lookup("env", "CONTROLLER_PASSWORD") }}'
+----

downstream/modules/platform/ref-controller-credential-aws.adoc

@@ -36,3 +36,16 @@ To use implicit IAM role credentials, do not attach AWS cloud credentials in {Co
 
 Attaching your AWS cloud credential to your job template forces the use of your AWS credentials and will not "fall through" to use your IAM role credentials (this is due to the use of the boto library.)
 ====
+
+== Access Amazon EC2 credentials in an ansible playbook
+
+You can get AWS credential parameters from a job runtime environment:
+
+[literal, options="nowrap" subs="+attributes"]
+----
+vars:
+  aws:
+    access_key: '{{ lookup("env", "AWS_ACCESS_KEY_ID") }}'
+    secret_key: '{{ lookup("env", "AWS_SECRET_ACCESS_KEY") }}'
+    security_token: '{{ lookup("env", "AWS_SECURITY_TOKEN") }}'
+----

downstream/modules/platform/ref-controller-credential-azure-resource.adoc

@@ -1,6 +1,6 @@
 [id="ref-controller-credential-azure-resource"]
 
-= Microsoft Azure Resource Manager
+= {Azure} Resource Manager
 
 Select this credential type to enable synchronization of cloud inventory with {Azure} Resource Manager.
 
@@ -60,3 +60,17 @@ ad_user
 password
 subscription_id
 ----
+
+== Access {Azure} resource manager credentials in an ansible playbook
+
+You can get {Azure} credential parameters from a job runtime environment:
+
+[literal, options="nowrap" subs="+attributes"]
+----
+vars:
+  azure:
+    client_id: '{{ lookup("env", "AZURE_CLIENT_ID") }}'
+    secret: '{{ lookup("env", "AZURE_SECRET") }}'
+    tenant: '{{ lookup("env", "AZURE_TENANT") }}'
+    subscription_id: '{{ lookup("env", "AZURE_SUBSCRIPTION_ID") }}'
+----

downstream/modules/platform/ref-controller-credential-machine.adoc

@@ -69,4 +69,16 @@ Sudo Password must be used in combination with SSH passwords or SSH Private Keys
 [WARNING]
 ====
 Credentials which are used in _Scheduled Jobs_ must not be configured as *Prompt on launch*.
-====
+====
+
+== Access machine credentials in an ansible playbook
+
+You can get username and password from Ansible facts:
+
+[literal, options="nowrap" subs="+attributes"]
+----
+vars:
+  machine:
+    username: '{{ ansible_user }}'
+    password: '{{ ansible_password }}'
+----

downstream/modules/platform/ref-controller-credential-network.adoc

@@ -33,4 +33,16 @@ Network credentials require the following inputs:
 * *Authorize*: Select this from the Options field to control whether or not to enter privileged mode.
 * If *Authorize* is checked, enter a password in the *Authorize Password* field to access privileged mode.
 
-For more information, see link:https://www.ansible.com/blog/porting-ansible-network-playbooks-with-new-connection-plugins[Porting Ansible Network Playbooks with New Connection Plugins].
+For more information, see link:https://www.ansible.com/blog/porting-ansible-network-playbooks-with-new-connection-plugins[Porting Ansible Network Playbooks with New Connection Plugins].
+
+= Access network credentials in an ansible playbook
+
+You can get the username and password parameters from a job runtime environment:
+
+[literal, options="nowrap" subs="+attributes"]
+----
+vars:
+  network:
+    username: '{{ lookup("env", "ANSIBLE_NET_USERNAME") }}'
+    password: '{{ lookup("env", "ANSIBLE_NET_PASSWORD") }}'
+----

downstream/modules/platform/ref-controller-credential-openShift.adoc

@@ -26,6 +26,4 @@ To set up a container group, you must have the following:
 If you do not want to give these roles to the service account, you can pre-create the `ImagePullSecrets` and specify them on the pod spec for the ContainerGroup. 
 In this case, the {ExecEnvShort} must not have a Container Registry credential associated, or {ControllerName} attempts to create the secret for you in the namespace.
 * A token associated with that service account (OpenShift or Kubernetes Bearer Token)
-* A CA certificate associated with the cluster
-
-include::proc-controller-credential-create-openshift-account.adoc[leveloffset=+1]
+* A CA certificate associated with the cluster

downstream/modules/platform/ref-controller-credential-types.adoc

@@ -34,32 +34,4 @@
 
 The credential types associated with Centrify, CyberArk, HashiCorp Vault, {Azure} _Key Management System_ (KMS), and Thycotic are part of the credential plugins capability that enables an external system to lookup your secrets information. 
 
-//For more information, see xref:assembly-controller-secret-management-system[Secrets Management System].
-
-include::ref-controller-credential-aws.adoc[leveloffset=+1]
-include::ref-controller-credential-galaxy-hub.adoc[leveloffset=+1]
-include::ref-controller-credential-centrify-vault.adoc[leveloffset=+1]
-include::ref-controller-credential-container-registry.adoc[leveloffset=+1]
-include::ref-controller-credential-cyberark-central.adoc[leveloffset=+1]
-include::ref-controller-credential-cyberark-conjur.adoc[leveloffset=+1]
-include::ref-controller-credential-gitHub-pat.adoc[leveloffset=+1]
-include::ref-controller-credential-gitLab-pat.adoc[leveloffset=+1]
-include::ref-controller-credential-GCE.adoc[leveloffset=+1]
-include::ref-controller-credential-GPG-public-key.adoc[leveloffset=+1]
-include::ref-controller-credential-hashiCorp-secret.adoc[leveloffset=+1]
-include::ref-controller-credential-hashiCorp-vault.adoc[leveloffset=+1]
-include::ref-controller-credential-insights.adoc[leveloffset=+1]
-include::ref-controller-credential-machine.adoc[leveloffset=+1]
-include::ref-controller-credential-azure-key.adoc[leveloffset=+1]
-include::ref-controller-credential-azure-resource.adoc[leveloffset=+1]
-include::ref-controller-credential-network.adoc[leveloffset=+1]
-include::ref-controller-credential-openShift.adoc[leveloffset=+1]
-include::ref-controller-credential-openStack.adoc[leveloffset=+1]
-include::ref-controller-credential-aap.adoc[leveloffset=+1]
-include::ref-controller-credential-satellite.adoc[leveloffset=+1]
-include::ref-controller-credential-virtualization.adoc[leveloffset=+1]
-include::ref-controller-credential-source-control.adoc[leveloffset=+1]
-include::ref-controller-credential-thycotic-vault.adoc[leveloffset=+1]
-include::ref-controller-credential-thycotic-server.adoc[leveloffset=+1]
-include::ref-controller-credential-vault.adoc[leveloffset=+1]
-include::ref-controller-credential-vmware-vcenter.adoc[leveloffset=+1]
+For more information, see xref:assembly-controller-secret-management[Secrets Management System].

downstream/modules/platform/ref-controller-credential-virtualization.adoc

@@ -23,4 +23,17 @@ To sync with the inventory, the credential URL needs to include the `ovirt-engin
 * *Username*: The username to use to connect to oVirt4. This must include the domain profile to succeed, for example
 `[email protected]`.
 * *Password*: The password to use to connect to it.
-* Optional: *CA File*: Provide an absolute path to the oVirt certificate file (it may end in `.pem`, `.cer` and `.crt` extensions, but preferably `.pem` for consistency)
+* Optional: *CA File*: Provide an absolute path to the oVirt certificate file (it may end in `.pem`, `.cer` and `.crt` extensions, but preferably `.pem` for consistency)
+
+== Access virtualization credentials in an ansible playbook
+
+You can get the RHV credential parameter from a job runtime environment:
+
+[literal, options="nowrap" subs="+attributes"]
+----
+vars:
+  ovirt:
+    ovirt_url: '{{ lookup("env", "OVIRT_URL") }}'
+    ovirt_username: '{{ lookup("env", "OVIRT_USERNAME") }}'
+    ovirt_password: '{{ lookup("env", "OVIRT_PASSWORD") }}'
+----

downstream/modules/platform/ref-controller-credential-vmware-vcenter.adoc

@@ -28,4 +28,17 @@ VMware credentials require the following inputs:
 [NOTE]
 ====
 If the VMware guest tools are not running on the instance, VMware inventory synchronization might not return an IP address for that instance.
-====
+====
+
+== Access VMware vCenter credentials in an ansible playbook
+
+You can get VMware vCenter credential parameters from a job runtime environment:
+
+[literal, options="nowrap" subs="+attributes"]
+----
+vars:
+  vmware:
+    host: '{{ lookup("env", "VMWARE_HOST") }}'
+    username: '{{ lookup("env", "VMWARE_USER") }}'
+    password: '{{ lookup("env", "VMWARE_PASSWORD") }}'
+----

downstream/modules/platform/ref-controller-use-credentials-in-playbooks.adoc

@@ -0,0 +1,75 @@
+[id="ref-controller-use-credentials-in-playbooks"]
+
+= Use {ControllerName} credentials in a playbook
+
+The following playbook is an example of how to use {ControllerName} credentials in your playbook.
+
+[literal, options="nowrap" subs="+attributes"]
+----
+- hosts: all
+
+  vars:
+    machine:
+      username: '{{ ansible_user }}'
+      password: '{{ ansible_password }}'
+    tower:
+      host: '{{ lookup("env", "TOWER_HOST") }}'
+      username: '{{ lookup("env", "TOWER_USERNAME") }}'
+      password: '{{ lookup("env", "TOWER_PASSWORD") }}'
+    network:
+      username: '{{ lookup("env", "ANSIBLE_NET_USERNAME") }}'
+      password: '{{ lookup("env", "ANSIBLE_NET_PASSWORD") }}'
+    aws:
+      access_key: '{{ lookup("env", "AWS_ACCESS_KEY_ID") }}'
+      secret_key: '{{ lookup("env", "AWS_SECRET_ACCESS_KEY") }}'
+      security_token: '{{ lookup("env", "AWS_SECURITY_TOKEN") }}'
+    vmware:
+      host: '{{ lookup("env", "VMWARE_HOST") }}'
+      username: '{{ lookup("env", "VMWARE_USER") }}'
+      password: '{{ lookup("env", "VMWARE_PASSWORD") }}'
+    gce:
+      email: '{{ lookup("env", "GCE_EMAIL") }}'
+      project: '{{ lookup("env", "GCE_PROJECT") }}'
+    azure:
+      client_id: '{{ lookup("env", "AZURE_CLIENT_ID") }}'
+      secret: '{{ lookup("env", "AZURE_SECRET") }}'
+      tenant: '{{ lookup("env", "AZURE_TENANT") }}'
+      subscription_id: '{{ lookup("env", "AZURE_SUBSCRIPTION_ID") }}'
+
+  tasks:
+    - debug:
+        var: machine
+
+    - debug:
+        var: tower
+
+    - debug:
+        var: network
+
+    - debug:
+        var: aws
+
+    - debug:
+        var: vmware
+
+    - debug:
+        var: gce
+
+    - shell: 'cat {{ gce.pem_file_path }}'
+      delegate_to: localhost
+
+    - debug:
+        var: azure
+----
+
+[discrete]
+== Use 'delegate_to' and any lookup variable
+
+[literal, options="nowrap" subs="+attributes"]
+----
+- command: somecommand
+  environment:
+    USERNAME: '{{ lookup("env", "USERNAME") }}'
+    PASSWORD: '{{ lookup("env", "PASSWORD") }}'
+  delegate_to: somehost
+----