diff options
| author | TVo <thavo@redhat.com> | 2024-09-16 23:27:58 +0200 |
|---|---|---|
| committer | GitHub <noreply@github.com> | 2024-09-16 23:27:58 +0200 |
| commit | ef8cb892cb8f2b8708e7358b9342da8a7c2e2a28 (patch) | |
| tree | 8c1118e2f99a790a5c2dc40b3af416ec25f715b8 /docs | |
| parent | Remove ML remnants from docs (#15500) (diff) | |
| download | awx-ef8cb892cb8f2b8708e7358b9342da8a7c2e2a28.tar.xz awx-ef8cb892cb8f2b8708e7358b9342da8a7c2e2a28.zip | |
Plugin removals for docs (#15505)
* Removed files from AWX that were moved to awx-plugins.
* Removed credential plugins file from AWX.
* Resolved broken build: added back missing graphics and removed obsolete xrefs.
Diffstat (limited to 'docs')
32 files changed, 0 insertions, 1179 deletions
diff --git a/docs/docsite/rst/administration/multi-creds-assignment.rst b/docs/docsite/rst/administration/multi-creds-assignment.rst index 9a95a928bf..8c1deba8a9 100644 --- a/docs/docsite/rst/administration/multi-creds-assignment.rst +++ b/docs/docsite/rst/administration/multi-creds-assignment.rst @@ -104,8 +104,4 @@ Passwords for Vault credentials that are marked with "Prompt on launch", the lau } -Linked credentials -^^^^^^^^^^^^^^^^^^^ - -Instead of uploading sensitive credential information into AWX, you can link credential fields to external systems and using them to run your playbooks. Refer to the :ref:`Secret Management System <ug_credential_plugins>` section of the |atu|. diff --git a/docs/docsite/rst/common/images/credentials-create-aws-secret-credential.png b/docs/docsite/rst/common/images/credentials-create-aws-secret-credential.png Binary files differdeleted file mode 100644 index 9c07dd904a..0000000000 --- a/docs/docsite/rst/common/images/credentials-create-aws-secret-credential.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/credentials-create-azure-kms-credential.png b/docs/docsite/rst/common/images/credentials-create-azure-kms-credential.png Binary files differdeleted file mode 100644 index 96897b10cd..0000000000 --- a/docs/docsite/rst/common/images/credentials-create-azure-kms-credential.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/credentials-create-centrify-vault-credential.png b/docs/docsite/rst/common/images/credentials-create-centrify-vault-credential.png Binary files differdeleted file mode 100644 index 023c1bfe37..0000000000 --- a/docs/docsite/rst/common/images/credentials-create-centrify-vault-credential.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/credentials-create-cyberark-ccp-credential.png b/docs/docsite/rst/common/images/credentials-create-cyberark-ccp-credential.png Binary files differdeleted file mode 100644 index 7cd97a433c..0000000000 --- a/docs/docsite/rst/common/images/credentials-create-cyberark-ccp-credential.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/credentials-create-cyberark-conjur-credential.png b/docs/docsite/rst/common/images/credentials-create-cyberark-conjur-credential.png Binary files differdeleted file mode 100644 index 50b49c7c53..0000000000 --- a/docs/docsite/rst/common/images/credentials-create-cyberark-conjur-credential.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/credentials-create-hashicorp-kv-credential.png b/docs/docsite/rst/common/images/credentials-create-hashicorp-kv-credential.png Binary files differdeleted file mode 100644 index 36a26a0505..0000000000 --- a/docs/docsite/rst/common/images/credentials-create-hashicorp-kv-credential.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/credentials-create-hashicorp-ssh-credential.png b/docs/docsite/rst/common/images/credentials-create-hashicorp-ssh-credential.png Binary files differdeleted file mode 100644 index bc7411c7e6..0000000000 --- a/docs/docsite/rst/common/images/credentials-create-hashicorp-ssh-credential.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/credentials-create-thycotic-devops-credential.png b/docs/docsite/rst/common/images/credentials-create-thycotic-devops-credential.png Binary files differdeleted file mode 100644 index 14aa3aa1ad..0000000000 --- a/docs/docsite/rst/common/images/credentials-create-thycotic-devops-credential.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/credentials-create-thycotic-server-credential.png b/docs/docsite/rst/common/images/credentials-create-thycotic-server-credential.png Binary files differdeleted file mode 100644 index 930f43a18b..0000000000 --- a/docs/docsite/rst/common/images/credentials-create-thycotic-server-credential.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/credentials-link-credential-prompt.png b/docs/docsite/rst/common/images/credentials-link-credential-prompt.png Binary files differdeleted file mode 100644 index 756dafa2d4..0000000000 --- a/docs/docsite/rst/common/images/credentials-link-credential-prompt.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/credentials-link-metadata-prompt.png b/docs/docsite/rst/common/images/credentials-link-metadata-prompt.png Binary files differdeleted file mode 100644 index 0e2e705057..0000000000 --- a/docs/docsite/rst/common/images/credentials-link-metadata-prompt.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/credentials-link-metadata-test-error.png b/docs/docsite/rst/common/images/credentials-link-metadata-test-error.png Binary files differdeleted file mode 100644 index 996e9dfea1..0000000000 --- a/docs/docsite/rst/common/images/credentials-link-metadata-test-error.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/credentials-machine-test-hashicorp-metadata.png b/docs/docsite/rst/common/images/credentials-machine-test-hashicorp-metadata.png Binary files differdeleted file mode 100644 index 813fe56f5e..0000000000 --- a/docs/docsite/rst/common/images/credentials-machine-test-hashicorp-metadata.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/inventories-create-source-AWS-example.png b/docs/docsite/rst/common/images/inventories-create-source-AWS-example.png Binary files differdeleted file mode 100644 index d4a532d4ef..0000000000 --- a/docs/docsite/rst/common/images/inventories-create-source-AWS-example.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/inventories-create-source-GCE-example.png b/docs/docsite/rst/common/images/inventories-create-source-GCE-example.png Binary files differdeleted file mode 100644 index a508e92ba2..0000000000 --- a/docs/docsite/rst/common/images/inventories-create-source-GCE-example.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/inventories-create-source-azurerm-example.png b/docs/docsite/rst/common/images/inventories-create-source-azurerm-example.png Binary files differdeleted file mode 100644 index bfc4ac7501..0000000000 --- a/docs/docsite/rst/common/images/inventories-create-source-azurerm-example.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/inventories-create-source-insights-example.png b/docs/docsite/rst/common/images/inventories-create-source-insights-example.png Binary files differdeleted file mode 100644 index 1aa7b679d0..0000000000 --- a/docs/docsite/rst/common/images/inventories-create-source-insights-example.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/inventories-create-source-ocpvirt-example.png b/docs/docsite/rst/common/images/inventories-create-source-ocpvirt-example.png Binary files differdeleted file mode 100644 index 3e1398aa38..0000000000 --- a/docs/docsite/rst/common/images/inventories-create-source-ocpvirt-example.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/inventories-create-source-openstack-example.png b/docs/docsite/rst/common/images/inventories-create-source-openstack-example.png Binary files differdeleted file mode 100644 index bdf440b622..0000000000 --- a/docs/docsite/rst/common/images/inventories-create-source-openstack-example.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/inventories-create-source-rhaap-example.png b/docs/docsite/rst/common/images/inventories-create-source-rhaap-example.png Binary files differdeleted file mode 100644 index 4aaeabf742..0000000000 --- a/docs/docsite/rst/common/images/inventories-create-source-rhaap-example.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/inventories-create-source-rhsat6-example.png b/docs/docsite/rst/common/images/inventories-create-source-rhsat6-example.png Binary files differdeleted file mode 100644 index 486171de46..0000000000 --- a/docs/docsite/rst/common/images/inventories-create-source-rhsat6-example.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/inventories-create-source-rhv-example.png b/docs/docsite/rst/common/images/inventories-create-source-rhv-example.png Binary files differdeleted file mode 100644 index de6f5c7f3e..0000000000 --- a/docs/docsite/rst/common/images/inventories-create-source-rhv-example.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/inventories-create-source-terraform-example.png b/docs/docsite/rst/common/images/inventories-create-source-terraform-example.png Binary files differdeleted file mode 100644 index 0ade0c3fa5..0000000000 --- a/docs/docsite/rst/common/images/inventories-create-source-terraform-example.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/inventories-create-source-vmware-example.png b/docs/docsite/rst/common/images/inventories-create-source-vmware-example.png Binary files differdeleted file mode 100644 index ee46cf6a7b..0000000000 --- a/docs/docsite/rst/common/images/inventories-create-source-vmware-example.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/key-mgmt-button.png b/docs/docsite/rst/common/images/key-mgmt-button.png Binary files differindex 05e4d0733e..6b167fe9c2 100644 --- a/docs/docsite/rst/common/images/key-mgmt-button.png +++ b/docs/docsite/rst/common/images/key-mgmt-button.png diff --git a/docs/docsite/rst/userguide/credential_plugins.rst b/docs/docsite/rst/userguide/credential_plugins.rst deleted file mode 100644 index 6ce53b862f..0000000000 --- a/docs/docsite/rst/userguide/credential_plugins.rst +++ /dev/null @@ -1,384 +0,0 @@ -.. _ug_credential_plugins: - -Secret Management System -============================= - -.. index:: - single: credentials - pair: credential; plugins - pair: secret management; credential - -Users and admins upload machine and cloud credentials so that automation can access machines and external services on their behalf. By default, sensitive credential values (such as SSH passwords, SSH private keys, API tokens for cloud services) are stored in the database after being encrypted. With external credentials backed by credential plugins, you can map credential fields (like a password or an SSH Private key) to values stored in a :term:`secret management system` instead of providing them to AWX directly. AWX provides a secret management system that include integrations for: - -- :ref:`ug_credentials_aws_lookup` -- :ref:`ug_credentials_centrify` -- :ref:`ug_credentials_cyberarkccp` -- :ref:`ug_credentials_cyberarkconjur` -- :ref:`ug_credentials_hashivault` (KV) -- :ref:`ug_credentials_hashivaultssh` -- :ref:`ug_credentials_azurekeyvault` (KMS) -- :ref:`ug_credentials_thycoticvault` -- :ref:`ug_credentials_thycoticserver` - -These external secret values will be fetched prior to running a playbook that needs them. For more information on specifying these credentials in the User Interface, see :ref:`ug_credentials`. - -Configure and link secret lookups ------------------------------------ - -When configuring AWX to pull a secret from a 3rd-party system, it is in essence linking credential fields to external systems. To link a credential field to a value stored in an external system, select the external credential corresponding to that system and provide :term:`metadata` to look up the desired value. The metadata input fields are part of the :term:`external credential type` definition of the :term:`source credential`. - -AWX provides a :term:`credential plugin` interface for developers, integrators, admins, and power-users with the ability to add new external credential types to extend it to support other secret management systems. For more detail, see the `development docs for credential plugins`_. - -.. _`development docs for credential plugins`: https://github.com/ansible/awx/blob/devel/docs/credentials/credential_plugins.md - - -Use the AWX User Interface to configure and use each of the supported 3-party secret management systems. - -1. First, create an external credential for authenticating with the secret management system. At minimum, provide a name for the external credential and select one of the following for the **Credential Type**: - -.. contents:: - :local: - -2. Navigate to the credential form of the target credential and link one or more input fields to the external credential along with metadata for locating the secret in the external system. In this example, the *Demo Credential* is the target credential. - -.. _ag_credential_plugins_link_step: - -3. For any of the fields below the **Type Details** area that you want to link to the external credential, click the |key| button of the input field. You are prompted to set the input source to use to retrieve your secret information. - -.. |key| image:: ../common/images/key-mgmt-button.png - :alt: Icon for managing external credentials -.. image:: ../common/images/credentials-link-credential-prompt.png - :alt: Credential section of the external secret management system dialog - -4. Select the credential you want to link to, and click **Next**. This takes you to the **Metadata** tab of the input source. Metadata is specific to the input source you select: - -.. list-table:: - :widths: 10 10 25 - :width: 1400px - :header-rows: 1 - - * - Input Source - - Metadata - - Description - * - *AWS Secrets Manager* - - AWS Secrets Manager Region (required) - - The region where the secrets manager is located. - * - - - AWS Secret Name (Required) - - Specify the AWS secret name that was generated by the AWS access key. - * - *Centrify Vault Credential Provider Lookup* - - Account Name (Required) - - Name of the system account or domain associated with Centrify Vault. - * - - - System Name - - Specify the name used by the Centrify portal. - * - *CyberArk Central Credential Provider Lookup* - - Object Query (Required) - - Lookup query for the object. - * - - - Object Query Format - - Select ``Exact`` for a specific secret name, or ``Regexp`` for a secret that has a dynamically generated name. - * - - - Object Property - - Specifies the name of the property to return (e.g., ``UserName``, ``Address``, etc.) other than the default of ``Content``. - * - - - Reason - - If required per the object's policy, supply a reason for checking out the secret, as CyberArk logs those. - * - *CyberArk Conjur Secrets Lookup* - - Secret Identifier - - The identifier for the secret. - * - - - Secret Version - - Specify a version of the secret, if necessary, otherwise, leave it empty to use the latest version. - * - *HashiVault Secret Lookup* - - Name of Secret Backend - - Specify the name of the KV backend to use. Leave it blank to use the first path segment of the **Path to Secret** field instead. - * - - - Path to Secret (required) - - Specify the path to where the secret information is stored; for example, ``/path/username``. - * - - - Key Name (required) - - Specify the name of the key to look up the secret information. - * - - - Secret Version (V2 Only) - - Specify a version if necessary, otherwise, leave it empty to use the latest version. - * - *HashiCorp Signed SSH* - - Unsigned Public Key (required) - - Specify the public key of the cert you want to get signed. It needs to be present in the authorized keys file of the target host(s). - * - - - Path to Secret (required) - - Specify the path to where the secret information is stored; for example, ``/path/username``. - * - - - Role Name (required) - - A role is a collection of SSH settings and parameters that are stored in Hashi vault. Typically, you can specify a couple of them with different privileges, timeouts, etc. So you could have a role that is allowed to get a cert signed for root, and other less privileged ones, for example. - * - - - Valid Principals - - Specify a user (or users) other than the default, that you are requesting vault to authorize the cert for the stored key. Hashi vault has a default user for whom it signs (e.g., ec2-user). - * - *Azure KMS* - - Secret Name (required) - - The actual name of the secret as it is referenced in Azure's Key vault app. - * - - - Secret Version - - Specify a version of the secret, if necessary, otherwise, leave it empty to use the latest version. - * - *Thycotic DevOps Secrets Vault* - - Secret Path (required) - - Specify the path to where the secret information is stored (e.g., /path/username). - * - *Thycotic Secret Server* - - Secret ID (required) - - The identifier for the secret. - * - - - Secret Field - - Specify the field to be used from the secret. - -This example shows the Metadata prompt for HashiVault Secret Lookup. - -.. image:: ../common/images/credentials-link-metadata-prompt.png - :alt: Metadata section of the external secret management system dialog - - -5. Click **Test** to verify connection to the secret management system. If the lookup is unsuccessful, an error message like this one displays: - -.. image:: ../common/images/credentials-link-metadata-test-error.png - :alt: Example exception dialog for credentials lookup - -6. When done, click **OK**. This closes the prompt window and returns you to the Details screen of your target credential. **Repeat these steps**, starting with :ref:`step 3 above <ag_credential_plugins_link_step>` to complete the remaining input fields for the target credential. By linking the information in this manner, AWX retrieves sensitive information, such as username, password, keys, certificates, and tokens from the 3rd-party management systems and populates that data into the remaining fields of the target credential form. - -7. If necessary, supply any information manually for those fields that do not use linking as a way of retrieving sensitive information. Refer to the appropriate :ref:`ug_credentials_cred_types` for more detail about each of the fields. - -8. Click **Save** when done. - - -.. _ug_credentials_aws_lookup: - -AWS Secrets Manager Lookup -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. index:: - pair: credential types; AWS - -This plugin allows AWS to be used as a credential input source to pull secrets from AWS SecretsManager. `AWS Secrets Manager <https://aws.amazon.com/secrets-manager/>`_ provides similar service to :ref:`ug_credentials_azurekeyvault`, and the AWS collection provides a lookup plugin for it. - -When **AWS Secrets Manager lookup** is selected for **Credential Type**, provide the following attributes to properly configure your lookup: - -- **AWS Access Key** (required): provide the access key used for communicating with AWS' key management system -- **AWS Secret Key** (required): provide the secret as obtained by the AWS IAM console - - -Below shows an example of a configured AWS Secret Manager credential. - -.. image:: ../common/images/credentials-create-aws-secret-credential.png - :width: 1400px - :alt: Example new AWS Secret Manager credential lookup dialog - - -.. _ug_credentials_centrify: - -Centrify Vault Credential Provider Lookup -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. index:: - pair: credential types; Centrify - -You need the Centrify Vault web service running to store secrets in order for this integration to work. When **Centrify Vault Credential Provider Lookup** is selected for **Credential Type**, provide the following attributes to properly configure your lookup: - -- **Centrify Tenant URL** (required): provide the URL used for communicating with Centrify's secret management system -- **Centrify API User** (required): provide the username -- **Centrify API Password** (required): provide the password -- **OAuth2 Application ID** : specify the identifier given associated with the OAuth2 client -- **OAuth2 Scope** : specify the scope of the OAuth2 client - - -Below shows an example of a configured CyberArk AIM credential. - -.. image:: ../common/images/credentials-create-centrify-vault-credential.png - :alt: Example new centrify vault credential lookup dialog - -.. _ug_credentials_cyberarkccp: - -CyberArk Central Credential Provider (CCP) Lookup -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. index:: - single: CyberArk CCP - pair: credential; CyberArk CCP - -You need the CyberArk Central Credential Provider web service running to store secrets in order for this integration to work. When **CyberArk Central Credential Provider Lookup** is selected for **Credential Type**, provide the following attributes to properly configure your lookup: - -- **CyberArk CCP URL** (required): provide the URL used for communicating with CyberArk CCP's secret management system; must include URL scheme (http, https, etc.) -- **Web Service ID**: optionally specify the identifier for the web service; leaving it blank defaults to AIMWebService -- **Application ID** (required): specify the identifier given by CyberArk CCP services -- **Client Key**: paste the client key if provided by CyberArk -- **Client Certificate**: include the ``BEGIN CERTIFICATE`` and ``END CERTIFICATE`` lines when pasting the certificate, if provided by CyberArk -- **Verify SSL Certificates**: this option is only available when the URL uses HTTPS. Check this option to verify the server’s SSL certificate is valid and trusted. Environments that use internal or private CA's should leave this option unchecked to disable verification. - -Below shows an example of a configured CyberArk CCP credential. - -.. image:: ../common/images/credentials-create-cyberark-ccp-credential.png - :alt: Example new CyberArk vault credential lookup dialog - -.. _ug_credentials_cyberarkconjur: - -CyberArk Conjur Secrets Manager Lookup -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. index:: - single: CyberArk Conjur - pair: credential; CyberArk Conjur - -With a Conjur Cloud tenant available to target, configure the CyberArk Conjur Secrets Lookup external management system credential plugin as documented. - -When **CyberArk Conjur Secrets Manager Lookup** is selected for **Credential Type**, provide the following attributes to properly configure your lookup: - -- **Conjur URL** (required): provide the URL used for communicating with CyberArk Conjur's secret management system; must include URL scheme (http, https, etc.) -- **API Key** (required): provide the key given by your Conjur admin -- **Account** (required): the organization's account name -- **Username** (required): the specific authenticated user for this service -- **Public Key Certificate**: include the ``BEGIN CERTIFICATE`` and ``END CERTIFICATE`` lines when pasting the public key, if provided by CyberArk - -Below shows an example of a configured CyberArk Conjur credential. - -.. image:: ../common/images/credentials-create-cyberark-conjur-credential.png - :alt: Example new CyberArk Conjur Secret lookup dialog - -.. _ug_credentials_hashivault: - -HashiCorp Vault Secret Lookup -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. index:: - single: HashiCorp Secret Lookup - pair: credential; HashiCorp KV - -When **HashiCorp Vault Secret Lookup** is selected for **Credential Type**, provide the following attributes to properly configure your lookup: - -- **Server URL** (required): provide the URL used for communicating with HashiCorp Vault's secret management system -- **Token**: specify the access token used to authenticate HashiCorp's server -- **CA Certificate**: specify the CA certificate used to verify HashiCorp's server -- **Approle Role_ID**: specify the ID if using Approle for authentication -- **Approle Secret_ID**: specify the corresponding secret ID for Approle authentication -- **Client Certificate**: specify a PEM-encoded client certificate when using the TLS auth method including any required intermediate certificates expected by Vault -- **Client Certificate Key**: specify a PEM-encoded certificate private key when using the TLS auth method -- **TLS Authentication Role**: specify the role or certificate name in Vault that corresponds to your client certificate when using the TLS auth method. If it is not provided, Vault will attempt to match the certificate automatically -- **Namespace name** specify the namespace name (Vault Enterprise only) -- **Kubernetes role** specify the role name when using Kubernetes authentication -- **Username**: enter the username of the user to be used to authenticate this service -- **Password**: enter the password associated with the user to authenticate this service -- **Path to Auth**: specify a path if other than the default path of ``/approle`` -- **API Version** (required): select v1 for static lookups and v2 for versioned lookups - - -For more detail about the Approle auth method and its fields, refer to the `Vault documentation for Approle Auth Method <https://developer.hashicorp.com/vault/docs/auth/approle>`_. - -LDAP authentication requires LDAP to be configured in HashiCorp's Vault UI. A policy may be added to the user if they want access to a specific engine created. As long as the bind is set properly, the user should be able to successfully authenticate. Cubbyhole is the name of the default secret mount. If you have proper permissions, you can create other mounts and write key values to those. For more detail about the LDAP auth method and its fields, refer to the `Vault documentation for LDAP auth method <https://developer.hashicorp.com/vault/docs/auth/ldap>`_. - -For more detail about the userpass auth method and its fields, refer to the `Vault documentation for userpass auth method <https://developer.hashicorp.com/vault/docs/auth/userpass>`_. - -For more detail about the Kubernetes auth method and its fields, refer to the `Vault documentation for Kubernetes auth method <https://developer.hashicorp.com/vault/docs/auth/kubernetes>`_. - -For more detail about the TLS certificate auth method and its fields, refer to the `Vault documentation for TLS certificates auth method <https://developer.hashicorp.com/vault/docs/auth/cert>`_. - -Below shows an example of a configured HashiCorp Vault Secret Lookup credential for LDAP. - -.. image:: ../common/images/credentials-create-hashicorp-kv-credential.png - :alt: Example new HashiCorp Vault Secret lookup dialog - -To test the lookup, create another credential that uses the HashiCorp Vault lookup. The example below shows the attributes for a machine credential configured to look up HashiCorp Vault secret credentials: - -.. image:: ../common/images/credentials-machine-test-hashicorp-metadata.png - :alt: Example machine credential lookup metadata for HashiCorp Vault. - - -.. _ug_credentials_hashivaultssh: - -HashiCorp Vault Signed SSH -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. index:: - single: HashiCorp SSH Secrets Engine - pair: credential; HashiCorp SSH Secrets Engine - -When **HashiCorp Vault Signed SSH** is selected for **Credential Type**, provide the following attributes to properly configure your lookup: - -- **Server URL** (required): provide the URL used for communicating with HashiCorp Signed SSH's secret management system -- **Token**: specify the access token used to authenticate HashiCorp's server -- **CA Certificate**: specify the CA certificate used to verify HashiCorp's server -- **Approle Role_ID**: specify the ID for Approle authentication -- **Approle Secret_ID**: specify the corresponding secret ID for Approle authentication -- **Client Certificate**: specify a PEM-encoded client certificate when using the TLS auth method including any required intermediate certificates expected by Vault -- **Client Certificate Key**: specify a PEM-encoded certificate private key when using the TLS auth method -- **TLS Authentication Role**: specify the role or certificate name in Vault that corresponds to your client certificate when using the TLS auth method. If it is not provided, Vault will attempt to match the certificate automatically -- **Namespace name** specify the namespace name (Vault Enterprise only) -- **Kubernetes role** specify the role name when using Kubernetes authentication -- **Username**: enter the username of the user to be used to authenticate this service -- **Password**: enter the password associated with the user to authenticate this service -- **Path to Auth**: specify a path if other than the default path of ``/approle`` - -For more detail about the Approle auth method and its fields, refer to the `Vault documentation for Approle Auth Method <https://developer.hashicorp.com/vault/docs/auth/approle>`_. - -For more detail about the Kubernetes auth method and its fields, refer to the `Vault documentation for Kubernetes auth method <https://developer.hashicorp.com/vault/docs/auth/kubernetes>`_. - -For more detail about the TLS certificate auth method and its fields, refer to the `Vault documentation for TLS certificates auth method <https://developer.hashicorp.com/vault/docs/auth/cert>`_. - -Below shows an example of a configured HashiCorp SSH Secrets Engine credential. - -.. image:: ../common/images/credentials-create-hashicorp-ssh-credential.png - :alt: Example new HashiCorp Vault Signed SSH credential lookup dialog - -.. _ug_credentials_azurekeyvault: - -Microsoft Azure Key Vault -~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. index:: - single: MS Azure KMS - pair: credential; MS Azure KMS - triple: credential; Azure; KMS - -When **Microsoft Azure Key Vault** is selected for **Credential Type**, provide the following attributes to properly configure your lookup: - -- **Vault URL (DNS Name)** (required): provide the URL used for communicating with MS Azure's key management system -- **Client ID** (required): provide the identifier as obtained by the Azure Active Directory -- **Client Secret** (required): provide the secret as obtained by the Azure Active Directory -- **Tenant ID** (required): provide the unique identifier that is associated with an Azure Active Directory instance within an Azure subscription -- **Cloud Environment**: select the applicable cloud environment to apply - -Below shows an example of a configured Microsoft Azure KMS credential. - -.. image:: ../common/images/credentials-create-azure-kms-credential.png - :alt: Example new Microsoft Azure Key Vault credential lookup dialog - -.. _ug_credentials_thycoticvault: - -Thycotic DevOps Secrets Vault -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. index:: - single: Thycotic DevOps Secrets Vault - pair: credential; Thycotic DevOps Secrets Vault - -When **Thycotic DevOps Secrets Vault** is selected for **Credential Type**, provide the following attributes to properly configure your lookup: - -- **Tenant** (required): provide the URL used for communicating with Thycotic's secret management system -- **Top-level Domain (TLD)** : provide the top-level domain designation (e.g., com, edu, org) associated with the secret vault you want to integrate -- **Client ID** (required): provide the identifier as obtained by the Thycotic secret management system -- **Client Secret** (required): provide the secret as obtained by the Thycotic secret management system - -Below shows an example of a configured Thycotic DevOps Secrets Vault credential. - -.. image:: ../common/images/credentials-create-thycotic-devops-credential.png - :alt: Example new Thycotic DevOps Secrets Vault credential lookup dialog - - - -.. _ug_credentials_thycoticserver: - -Thycotic Secret Server -~~~~~~~~~~~~~~~~~~~~~~~ -.. index:: - single: Thycotic Secret Server - pair: credential; Thycotic Secret Server - -When **Thycotic Secrets Server** is selected for **Credential Type**, provide the following attributes to properly configure your lookup: - -- **Secret Server URL** (required): provide the URL used for communicating with the Thycotic Secrets Server management system -- **Username** (required): specify the authenticated user for this service -- **Password** (required): provide the password associated with the user - -Below shows an example of a configured Thycotic Secret Server credential. - -.. image:: ../common/images/credentials-create-thycotic-server-credential.png - :alt: Example new Thycotic Secret Server credential lookup dialog - - diff --git a/docs/docsite/rst/userguide/credentials.rst b/docs/docsite/rst/userguide/credentials.rst index 1b2cfbe81b..55c011303d 100644 --- a/docs/docsite/rst/userguide/credentials.rst +++ b/docs/docsite/rst/userguide/credentials.rst @@ -128,8 +128,6 @@ The following credential types are supported with AWX: .. contents:: :local: -The credential types associated with AWS Secrets Manager, Centrify, CyberArk, HashiCorp Vault, Microsoft Azure Key Management System (KMS), and Thycotic are part of the credential plugins capability that allows an external system to lookup your secrets information. See the :ref:`ug_credential_plugins` section for further detail. - .. _ug_credentials_aws: @@ -166,10 +164,6 @@ AWX provides support for EC2 STS tokens (sometimes referred to as IAM STS creden To use implicit IAM role credentials, do not attach AWS cloud credentials in AWX when relying on IAM roles to access the AWS API. While it may seem to make sense to attach your AWS cloud credential to your job template, doing so will force 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.) -AWS Secrets Manager -^^^^^^^^^^^^^^^^^^^^^ -This is considered part of the secret management capability. See :ref:`ug_credentials_aws_lookup` for more detail. - Ansible Galaxy/Automation Hub API Token ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -190,11 +184,6 @@ To populate the **Galaxy Server URL** and the **Auth Server URL** fields, look f :alt: Hub console tokens page -Centrify Vault Credential Provider Lookup -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -This is considered part of the secret management capability. See :ref:`ug_credentials_centrify` for more detail. - - Container Registry ^^^^^^^^^^^^^^^^^^^ .. index:: @@ -210,16 +199,6 @@ Aside from specifying a name, the **Authentication URL** is the only required fi :alt: Credentials - create container credential form -CyberArk Central Credential Provider Lookup -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -This is considered part of the secret management capability. See :ref:`ug_credentials_cyberarkccp` for more detail. - - -CyberArk Conjur Secrets Manager Lookup -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -This is considered part of the secret management capability. See :ref:`ug_credentials_cyberarkconjur` for more detail. - - .. _ug_credentials_github: GitHub Personal Access Token @@ -305,17 +284,6 @@ Selecting this credential type allows you to create a credential that gives AWX See :ref:`ug_content_signing` for detailed information on how to generate a valid keypair, use the CLI tool to sign content, and how to add the public key to AWX. - -HashiCorp Vault Secret Lookup -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -This is considered part of the secret management capability. See :ref:`ug_credentials_hashivault` for more detail. - - -HashiCorp Vault Signed SSH -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -This is considered part of the secret management capability. See :ref:`ug_credentials_hashivaultssh` for more detail. - - Insights ^^^^^^^^^^^ @@ -387,11 +355,6 @@ Machine credentials have several attributes that may be configured: Credentials which are used in *Scheduled Jobs* must not be configured as "**Prompt on launch**". -Microsoft Azure Key Vault -^^^^^^^^^^^^^^^^^^^^^^^^^^^ -This is considered part of the secret management capability. See :ref:`ug_credentials_azurekeyvault` for more detail. - - Microsoft Azure Resource Manager ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -646,47 +609,6 @@ Source Control credentials have several attributes that may be configured: If you are using a GitHub account for a Source Control credential and you have 2FA (Two Factor Authentication) enabled on your account, you will need to use your Personal Access Token in the password field rather than your account password. -.. _ug_credentials_terraform: - -Terraform backend configuration -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -.. index:: - pair: credential types; Terraform - pair: backend configuration; Terraform - - -Terraform is a HashiCorp tool used to automate various infrastructure tasks. Select this credential type to enable synchronization with the Terraform inventory source. - -The Terraform credential requires the **Backend configuration** attribute which should contain the data from a `Terraform backend block <https://developer.hashicorp.com/terraform/language/settings/backends/configuration>`_. You can paste, drag a file, browse to upload a file, or click the (|key icon|) button to populate the field from an external :ref:`ug_credential_plugins`. An example configuration for an S3 backend: - -.. |key icon| image:: ../common/images/key-mgmt-button.png - :alt: Credentials - create Terraform backend configuration credential form - -:: - - bucket = "my-terraform-state-bucket" - key = "path/to/terraform-state-file" - region = "us-east-1" - access_key = "my-aws-access-key" - secret_key = "my-aws-secret-access-key" - -|Credentials - create terraform credential| - -.. |Credentials - create terraform credential| image:: ../common/images/credentials-create-terraform-credential.png - :alt: Credentials - create Terraform backend configuration credential form - -Saving it stores the file path to the backend configuration in an environment variable ``TF_BACKEND_CONFIG_FILE`` that is made available to any job with the credential attached. - - -Thycotic DevOps Secrets Vault -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -This is considered part of the secret management capability. See :ref:`ug_credentials_thycoticvault` for more detail. - - -Thycotic Secret Server -^^^^^^^^^^^^^^^^^^^^^^^^^^^ -This is considered part of the secret management capability. See :ref:`ug_credentials_thycoticserver` for more detail. Vault diff --git a/docs/docsite/rst/userguide/index.rst b/docs/docsite/rst/userguide/index.rst index 647f0e302b..e5550d2d28 100644 --- a/docs/docsite/rst/userguide/index.rst +++ b/docs/docsite/rst/userguide/index.rst @@ -30,14 +30,12 @@ Need help or want to discuss AWX including the documentation? See the :ref:`Comm rbac credentials credential_types - credential_plugins applications_auth execution_environments ee_reference projects project-sign inventories - inventory_plugins_templates job_templates job_slices workflows diff --git a/docs/docsite/rst/userguide/insights.rst b/docs/docsite/rst/userguide/insights.rst index 907ad157fd..e7dc09a26c 100644 --- a/docs/docsite/rst/userguide/insights.rst +++ b/docs/docsite/rst/userguide/insights.rst @@ -98,7 +98,6 @@ Create Insights Inventory The Insights playbook contains a `hosts:` line where the value is the hostname that Insights itself knows about, which may be different than the hostname that AWX knows about. To use an Insights playbook, you will need an Insights inventory. -To create a new inventory for use with Insights, see :ref:`ug_source_insights`. Remediate Insights Inventory ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/docs/docsite/rst/userguide/inventories.rst b/docs/docsite/rst/userguide/inventories.rst index 0f4823efbf..ee966f0c5e 100644 --- a/docs/docsite/rst/userguide/inventories.rst +++ b/docs/docsite/rst/userguide/inventories.rst @@ -471,34 +471,6 @@ Example of a constructed inventory details view: :alt: Constructed inventory details -.. _ug_inventories_plugins: - -Inventory Plugins -=================== - -.. index:: - pair: inventories; plugins - -Inventory updates use dynamically-generated YAML files which are parsed by their respective inventory plugin. Users can provide the new style inventory plugin config directly to AWX via the inventory source ``source_vars`` for all the following inventory sources: - -- :ref:`ug_source_ec2` -- :ref:`ug_source_gce` -- :ref:`ug_source_azure` -- :ref:`ug_source_vmvcenter` -- :ref:`ug_source_satellite` -- :ref:`ug_source_insights` -- :ref:`ug_source_openstack` -- :ref:`ug_source_rhv` -- :ref:`ug_source_rhaap` -- :ref:`ug_source_terraform` -- :ref:`ug_source_ocpv` - - -Newly created configurations for inventory sources will contain the default plugin configuration values. If you want your newly created inventory sources to match the output of legacy sources, you must apply a specific set of configuration values for that source. To ensure backward compatibility, AWX uses "templates" for each of these sources to force the output of inventory plugins into the legacy format. Refer to :ref:`ir_inv_plugin_templates_reference` section of this guide for each source and their respective templates to help you migrate to the new style inventory plugin output. - -``source_vars`` that contain ``plugin: foo.bar.baz`` as a top-level key will be replaced with the appropriate fully-qualified inventory plugin name at runtime based on the ``InventorySource`` source. For example, if ec2 is selected for the ``InventorySource`` then, at run-time, plugin will be set to ``amazon.aws.aws_ec2``. - - .. _ug_inventories_add: Add a new inventory @@ -914,294 +886,6 @@ An inventory that is sourced from a project means that is uses the SCM type from .. note:: If you are executing a custom inventory script from SCM, please make sure you set the execution bit (i.e. ``chmod +x``) on the script in your upstream source control. If you do not, AWX will throw a ``[Errno 13] Permission denied`` error upon execution. - -.. _ug_source_ec2: - -Amazon Web Services EC2 -~~~~~~~~~~~~~~~~~~~~~~~~ - -.. index:: - pair: inventories; Amazon Web Services - -1. To configure an AWS EC2-sourced inventory, select **Amazon EC2** from the Source field. - -2. The Create Source window expands with additional fields. Enter the following details: - - - **Credential**: Optionally choose from an existing AWS credential (for more information, refer to :ref:`ug_credentials`). - - If AWX is running on an EC2 instance with an assigned IAM Role, the credential may be omitted, and the security credentials from the instance metadata will be used instead. For more information on using IAM Roles, refer to the `IAM_Roles_for_Amazon_EC2_documentation_at_Amazon <http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam- roles-for-amazon-ec2.html>`_. - -3. You can optionally specify the verbosity, host filter, enabled variable/value, and update options as described in the main procedure for :ref:`adding a source <ug_add_inv_common_fields>`. - -4. Use the **Source Variables** field to override variables used by the ``aws_ec2`` inventory plugin. Enter variables using either JSON or YAML syntax. Use the radio button to toggle between the two. For a detailed description of these variables, view the `aws_ec2 inventory plugin documentation <https://cloud.redhat.com/ansible/automation-hub/repo/published/amazon/aws/content/inventory/aws_ec2>`__. - -|Inventories - create source - AWS EC2 example| - -.. |Inventories - create source - AWS EC2 example| image:: ../common/images/inventories-create-source-AWS-example.png - :alt: Inventories create source AWS example - - -.. note:: - - If you only use ``include_filters``, the AWS plugin always returns all the hosts. To use this properly, the first condition on the ``or`` must be on ``filters`` and then build the rest of the ``OR`` conditions on a list of ``include_filters``. - -.. _ug_source_gce: - -Google Compute Engine -~~~~~~~~~~~~~~~~~~~~~~~~ - -.. index:: - pair: inventories; Google Compute Engine - -1. To configure a Google-sourced inventory, select **Google Compute Engine** from the Source field. - -2. The Create Source window expands with the required **Credential** field. Choose from an existing GCE Credential. For more information, refer to :ref:`ug_credentials`. - -|Inventories - create source - GCE example| - -.. |Inventories - create source - GCE example| image:: ../common/images/inventories-create-source-GCE-example.png - :alt: Inventories create source Google compute engine example - -3. You can optionally specify the verbosity, host filter, enabled variable/value, and update options as described in the main procedure for :ref:`adding a source <ug_add_inv_common_fields>`. - -4. Use the **Source Variables** field to override variables used by the ``gcp_compute`` inventory plugin. Enter variables using either JSON or YAML syntax. Use the radio button to toggle between the two. For a detailed description of these variables, view the `gcp_compute inventory plugin documentation <https://cloud.redhat.com/ansible/automation-hub/repo/published/google/cloud/content/inventory/gcp_compute>`__. - - -.. _ug_source_azure: - -Microsoft Azure Resource Manager -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. index:: - pair: inventories; Microsoft Azure Resource Manager - -1. To configure a Azure Resource Manager-sourced inventory, select **Microsoft Azure Resource Manager** from the Source field. - -2. The Create Source window expands with the required **Credential** field. Choose from an existing Azure Credential. For more information, refer to :ref:`ug_credentials`. - -3. You can optionally specify the verbosity, host filter, enabled variable/value, and update options as described in the main procedure for :ref:`adding a source <ug_add_inv_common_fields>`. - -4. Use the **Source Variables** field to override variables used by the ``azure_rm`` inventory plugin. Enter variables using either JSON or YAML syntax. Use the radio button to toggle between the two. For a detailed description of these variables, view the `azure_rm inventory plugin documentation <https://cloud.redhat.com/ansible/automation-hub/repo/published/azure/azcollection/content/inventory/azure_rm>`__. - -|Inventories - create source - Azure RM example| - -.. |Inventories - create source - Azure RM example| image:: ../common/images/inventories-create-source-azurerm-example.png - :alt: Inventories create source Azure example - -.. _ug_source_vmvcenter: - -VMware vCenter -~~~~~~~~~~~~~~~~ - -.. index:: - pair: inventories; VMware vCenter - - -1. To configure a VMWare-sourced inventory, select **VMware vCenter** from the Source field. - -2. The Create Source window expands with the required **Credential** field. Choose from an existing VMware Credential. For more information, refer to :ref:`ug_credentials`. - -3. You can optionally specify the verbosity, host filter, enabled variable/value, and update options as described in the main procedure for :ref:`adding a source <ug_add_inv_common_fields>`. - -4. Use the **Source Variables** field to override variables used by the ``vmware_inventory`` inventory plugin. Enter variables using either JSON or YAML syntax. Use the radio button to toggle between the two. For a detailed description of these variables, view the `vmware_inventory inventory plugin <https://github.com/ansible-collections/community.vmware/blob/main/plugins/inventory/vmware_vm_inventory.py>`__. - - Starting with Ansible 2.9, VMWare properties have changed from lower case to camelCase. AWX provides aliases for the top-level keys, but lower case keys in nested properties have been discontinued. - For a list of valid and supported properties starting with Ansible 2.9, refer to `virtual machine attributes in the VMware dynamic inventory plugin <https://docs.ansible.com/ansible/latest/collections/community/vmware/docsite/vmware_scenarios/vmware_inventory_vm_attributes.html>`_. - -|Inventories - create source - VMware example| - -.. |Inventories - create source - VMWare example| image:: ../common/images/inventories-create-source-vmware-example.png - :alt: Inventories create source VMWare example - -.. _ug_source_satellite: - -Red Hat Satellite 6 -~~~~~~~~~~~~~~~~~~~~~~~~ - -.. index:: - pair: inventories; Red Hat Satellite 6 - -1. To configure a Red Hat Satellite-sourced inventory, select **Red Hat Satellite** from the Source field. - -2. The Create Source window expands with the required **Credential** field. Choose from an existing Satellite Credential. For more information, refer to :ref:`ug_credentials`. - -3. You can optionally specify the verbosity, host filter, enabled variable/value, and update options as described in the main procedure for :ref:`adding a source <ug_add_inv_common_fields>`. - -4. Use the **Source Variables** field to specify parameters used by the foreman inventory source. Enter variables using either JSON or YAML syntax. Use the radio button to toggle between the two. For a detailed description of these variables, refer to the `theforeman.foreman.foreman – Foreman inventory source <https://docs.ansible.com/ansible/latest/collections/theforeman/foreman/foreman_inventory.html>`_ in the Ansible documentation. - - -|Inventories - create source - RH Satellite example| - -.. |Inventories - create source - RH Satellite example| image:: ../common/images/inventories-create-source-rhsat6-example.png - :alt: Inventories create source Red Hat Satellite example - -If you encounter an issue with AWX inventory not having the "related groups" from Satellite, you might need to define these variables in the inventory source. See the inventory plugins template example for :ref:`ir_plugin_satellite` in the |atir| for detail. - - -.. _ug_source_insights: - -Red Hat Insights -~~~~~~~~~~~~~~~~~ - -.. index:: - pair: inventories; Red Hat Insights - -1. To configure a Red Hat Insights-sourced inventory, select **Red Hat Insights** from the Source field. - -2. The Create Source window expands with the required **Credential** field. Choose from an existing Insights Credential. For more information, refer to :ref:`ug_credentials`. - -3. You can optionally specify the verbosity, host filter, enabled variable/value, and update options as described in the main procedure for :ref:`adding a source <ug_add_inv_common_fields>`. - -4. Use the **Source Variables** field to override variables used by the ``insights`` inventory plugin. Enter variables using either JSON or YAML syntax. Use the radio button to toggle between the two. For a detailed description of these variables, view the `insights inventory plugin <https://cloud.redhat.com/ansible/automation-hub/repo/published/redhat/insights/content/inventory/insights>`__. - - -|Inventories - create source - RH Insights example| - -.. |Inventories - create source - RH Insights example| image:: ../common/images/inventories-create-source-insights-example.png - :alt: Inventories create source Red Hat Insights example - -.. _ug_source_openstack: - -OpenStack -~~~~~~~~~~~~ - -.. index:: - pair: inventories; OpenStack - - -1. To configure an OpenStack-sourced inventory, select **OpenStack** from the Source field. - -2. The Create Source window expands with the required **Credential** field. Choose from an existing OpenStack Credential. For more information, refer to :ref:`ug_credentials`. - -3. You can optionally specify the verbosity, host filter, enabled variable/value, and update options as described in the main procedure for :ref:`adding a source <ug_add_inv_common_fields>`. - -4. Use the **Source Variables** field to override variables used by the ``openstack`` inventory plugin. Enter variables using either JSON or YAML syntax. Use the radio button to toggle between the two. For a detailed description of these variables, view the `openstack inventory plugin <https://docs.ansible.com/ansible/latest/collections/openstack/cloud/openstack_inventory.html>`_ in the Ansible collections documentation. - -|Inventories - create source - OpenStack example| - -.. |Inventories - create source - OpenStack example| image:: ../common/images/inventories-create-source-openstack-example.png - :alt: Inventories create source OpenStack example - -.. _ug_source_rhv: - -Red Hat Virtualization -~~~~~~~~~~~~~~~~~~~~~~~~ - -.. index:: - pair: inventories; Red Hat Virtualization - -1. To configure a Red Hat Virtualization-sourced inventory, select **Red Hat Virtualization** from the Source field. - -2. The Create Source window expands with the required **Credential** field. Choose from an existing Red Hat Virtualization Credential. For more information, refer to :ref:`ug_credentials`. - -3. You can optionally specify the verbosity, host filter, enabled variable/value, and update options as described in the main procedure for :ref:`adding a source <ug_add_inv_common_fields>`. - -4. Use the **Source Variables** field to override variables used by the ``ovirt`` inventory plugin. Enter variables using either JSON or YAML syntax. Use the radio button to toggle between the two. For a detailed description of these variables, view the `ovirt inventory plugin <https://cloud.redhat.com/ansible/automation-hub/repo/published/redhat/rhv/content/inventory/ovirt>`__. - -|Inventories - create source - RHV example| - -.. |Inventories - create source - RHV example| image:: ../common/images/inventories-create-source-rhv-example.png - :alt: Inventories create source Red Hat Virtualization example - - -.. note:: - - Red Hat Virtualization (ovirt) inventory source requests are secure by default. To change this default setting, set the key ``ovirt_insecure`` to **true** in ``source_variables``, which is only available from the API details of the inventory source at the ``/api/v2/inventory_sources/N/`` endpoint. - -.. _ug_source_rhaap: - -Red Hat Ansible Automation Platform -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. index:: - pair: inventories; Red Hat Ansible Automation Platform - - -1. To configure this type of sourced inventory, select **Red Hat Ansible Automation Platform** from the Source field. - -2. The Create Source window expands with the required **Credential** field. Choose from an existing Ansible Automation Platform Credential. For more information, refer to :ref:`ug_credentials`. - -3. You can optionally specify the verbosity, host filter, enabled variable/value, and update options as described in the main procedure for :ref:`adding a source <ug_add_inv_common_fields>`. - - .. image:: ../common/images/inventories-create-source-rhaap-example.png - :alt: Inventories create source Red Hat Ansible Automation Platform example - -4. Use the **Source Variables** field to override variables used by the ``controller`` inventory plugin. Enter variables using either JSON or YAML syntax. Use the radio button to toggle between the two. - - -.. _ug_source_terraform: - -Terraform State -~~~~~~~~~~~~~~~~ - -.. index:: - pair: inventories; Terraform - pair: inventory source; Terraform state - - -This inventory source uses the `terraform_state <https://github.com/ansible-collections/cloud.terraform/blob/main/docs/cloud.terraform.terraform_state_inventory.rst>`_ inventory plugin from the `cloud.terraform <https://github.com/ansible-collections/cloud.terraform>`_ collection. The plugin will parse a terraform state file and add hosts for AWS EC2, GCE, and Azure instances. - -1. To configure this type of sourced inventory, select **Terraform State** from the Source field. - -2. The Create new source window expands with the required **Credential** field. Choose from an existing Terraform backend credential. For more information, refer to :ref:`ug_credentials_terraform`. - -3. You can optionally specify the verbosity, host filter, enabled variable/value, and update options as described in the main procedure for :ref:`adding a source <ug_add_inv_common_fields>`. For Terraform, enable **Overwrite** and **Update on launch** options. - -4. Use the **Source Variables** field to override variables used by the ``terraform`` inventory plugin. Enter variables using either JSON or YAML syntax. Use the radio button to toggle between the two. For more information on these variables, see the `terraform_state <https://github.com/ansible-collections/cloud.terraform/blob/main/docs/cloud.terraform.terraform_state_inventory.rst>`_ file for detail. - - The ``backend_type`` variable is required by the Terraform state inventory plugin. This should match the remote backend configured in the Terraform backend credential, here is an example for an Amazon S3 backend: - - :: - - --- - backend_type: s3 - -5. Enter an |ee| in the **Execution Environment** field that contains a Terraform binary. This is required for the inventory plugin to run the Terraform commands that read inventory data from the Terraform state file. Refer to the `Terraform EE readme <https://github.com/ansible-cloud/terraform_ee>`_ that contains an example |ee| configuration with a Terraform binary. - - .. image:: ../common/images/inventories-create-source-terraform-example.png - :alt: Inventories create source Terraform example - -6. To add hosts for AWS EC2, GCE, and Azure instances, the Terraform state file in the backend must contain state for resources already deployed to EC2, GCE, or Azure. Refer to each of the Terraform providers' respective documentation to provision instances. - - -.. _ug_source_ocpv: - -OpenShift Virtualization -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. index:: - pair: inventories; OpenShift - pair: inventories; OCP - pair: inventory source; OpenShift virtualization - - -This inventory source uses a cluster that is able to deploy OpenShift (OCP) virtualization. In order to configure an OCP virtualization requires a virtual machine deployed in a specific namespace and an OpenShift or Kubernetes API Bearer Token credential. - -1. To configure this type of sourced inventory, select **OpenShift Virtualization** from the Source field. -2. The Create new source window expands with the required **Credential** field. Choose from an existing Kubernetes API Bearer Token credential. For more information, refer to :ref:`ug_credentials_ocp_k8s`. In this example, the ``cmv2.engineering.redhat.com`` credential is used. - -3. You can optionally specify the verbosity, host filter, enabled variable/value, and update options as described in the main procedure for :ref:`adding a source <ug_add_inv_common_fields>`. - -4. Use the **Source Variables** field to override variables used by the ``kubernetes`` inventory plugin. Enter variables using either JSON or YAML syntax. Use the radio button to toggle between the two. For more information on these variables, see the `kubevirt.core.kubevirt inventory source <https://kubevirt.io/kubevirt.core/main/plugins/kubevirt.html#parameters>`_ documentation for detail. - - In the example below, the ``connections`` variable is used to specify access to a particular namespace in a cluster. - - :: - - --- - connections: - - namespaces: - - hao-test - - - .. image:: ../common/images/inventories-create-source-ocpvirt-example.png - :alt: Inventories create source OpenShift virtualization example - -5. Save the configuration and click the **Sync** button to sync the inventory. - - - - .. _ug_customscripts: Export old inventory scripts diff --git a/docs/docsite/rst/userguide/inventory_plugins_templates.rst b/docs/docsite/rst/userguide/inventory_plugins_templates.rst deleted file mode 100644 index 3fee4cd252..0000000000 --- a/docs/docsite/rst/userguide/inventory_plugins_templates.rst +++ /dev/null @@ -1,394 +0,0 @@ -.. _ir_inv_plugin_templates_reference: - -Supported Inventory Plugin Templates -============================================== - -.. index:: - pair: templates;inventory plugins - -Upon upgrades, existing configurations will be migrated to the new format that will produce a backwards compatible inventory output. Use the templates below to help aid in migrating your inventories to the new style inventory plugin output. - -.. contents:: - :local: - - -Amazon Web Services EC2 ------------------------- - -.. index:: - pair: inventories; Amazon Web Services - pair: inventories; aws - pair: inventory plugins; aws - -:: - - compose: - ansible_host: public_ip_address - ec2_account_id: owner_id - ec2_ami_launch_index: ami_launch_index | string - ec2_architecture: architecture - ec2_block_devices: dict(block_device_mappings | map(attribute='device_name') | list | zip(block_device_mappings | map(attribute='ebs.volume_id') | list)) - ec2_client_token: client_token - ec2_dns_name: public_dns_name - ec2_ebs_optimized: ebs_optimized - ec2_eventsSet: events | default("") - ec2_group_name: placement.group_name - ec2_hypervisor: hypervisor - ec2_id: instance_id - ec2_image_id: image_id - ec2_instance_profile: iam_instance_profile | default("") - ec2_instance_type: instance_type - ec2_ip_address: public_ip_address - ec2_kernel: kernel_id | default("") - ec2_key_name: key_name - ec2_launch_time: launch_time | regex_replace(" ", "T") | regex_replace("(\+)(\d\d):(\d)(\d)$", ".\g<2>\g<3>Z") - ec2_monitored: monitoring.state in ['enabled', 'pending'] - ec2_monitoring_state: monitoring.state - ec2_persistent: persistent | default(false) - ec2_placement: placement.availability_zone - ec2_platform: platform | default("") - ec2_private_dns_name: private_dns_name - ec2_private_ip_address: private_ip_address - ec2_public_dns_name: public_dns_name - ec2_ramdisk: ramdisk_id | default("") - ec2_reason: state_transition_reason - ec2_region: placement.region - ec2_requester_id: requester_id | default("") - ec2_root_device_name: root_device_name - ec2_root_device_type: root_device_type - ec2_security_group_ids: security_groups | map(attribute='group_id') | list | join(',') - ec2_security_group_names: security_groups | map(attribute='group_name') | list | join(',') - ec2_sourceDestCheck: source_dest_check | default(false) | lower | string - ec2_spot_instance_request_id: spot_instance_request_id | default("") - ec2_state: state.name - ec2_state_code: state.code - ec2_state_reason: state_reason.message if state_reason is defined else "" - ec2_subnet_id: subnet_id | default("") - ec2_tag_Name: tags.Name - ec2_virtualization_type: virtualization_type - ec2_vpc_id: vpc_id | default("") - filters: - instance-state-name: - - running - groups: - ec2: true - hostnames: - - network-interface.addresses.association.public-ip - - dns-name - - private-dns-name - keyed_groups: - - key: image_id | regex_replace("[^A-Za-z0-9\_]", "_") - parent_group: images - prefix: '' - separator: '' - - key: placement.availability_zone - parent_group: zones - prefix: '' - separator: '' - - key: ec2_account_id | regex_replace("[^A-Za-z0-9\_]", "_") - parent_group: accounts - prefix: '' - separator: '' - - key: ec2_state | regex_replace("[^A-Za-z0-9\_]", "_") - parent_group: instance_states - prefix: instance_state - - key: platform | default("undefined") | regex_replace("[^A-Za-z0-9\_]", "_") - parent_group: platforms - prefix: platform - - key: instance_type | regex_replace("[^A-Za-z0-9\_]", "_") - parent_group: types - prefix: type - - key: key_name | regex_replace("[^A-Za-z0-9\_]", "_") - parent_group: keys - prefix: key - - key: placement.region - parent_group: regions - prefix: '' - separator: '' - - key: security_groups | map(attribute="group_name") | map("regex_replace", "[^A-Za-z0-9\_]", "_") | list - parent_group: security_groups - prefix: security_group - - key: dict(tags.keys() | map("regex_replace", "[^A-Za-z0-9\_]", "_") | list | zip(tags.values() - | map("regex_replace", "[^A-Za-z0-9\_]", "_") | list)) - parent_group: tags - prefix: tag - - key: tags.keys() | map("regex_replace", "[^A-Za-z0-9\_]", "_") | list - parent_group: tags - prefix: tag - - key: vpc_id | regex_replace("[^A-Za-z0-9\_]", "_") - parent_group: vpcs - prefix: vpc_id - - key: placement.availability_zone - parent_group: '{{ placement.region }}' - prefix: '' - separator: '' - plugin: amazon.aws.aws_ec2 - use_contrib_script_compatible_sanitization: true - - -Google Compute Engine ----------------------- - -.. index:: - pair: inventories; Google Compute Engine - pair: inventories; gce - pair: inventory plugins; gce - -:: - - auth_kind: serviceaccount - compose: - ansible_ssh_host: networkInterfaces[0].accessConfigs[0].natIP | default(networkInterfaces[0].networkIP) - gce_description: description if description else None - gce_id: id - gce_image: image - gce_machine_type: machineType - gce_metadata: metadata.get("items", []) | items2dict(key_name="key", value_name="value") - gce_name: name - gce_network: networkInterfaces[0].network.name - gce_private_ip: networkInterfaces[0].networkIP - gce_public_ip: networkInterfaces[0].accessConfigs[0].natIP | default(None) - gce_status: status - gce_subnetwork: networkInterfaces[0].subnetwork.name - gce_tags: tags.get("items", []) - gce_zone: zone - hostnames: - - name - - public_ip - - private_ip - keyed_groups: - - key: gce_subnetwork - prefix: network - - key: gce_private_ip - prefix: '' - separator: '' - - key: gce_public_ip - prefix: '' - separator: '' - - key: machineType - prefix: '' - separator: '' - - key: zone - prefix: '' - separator: '' - - key: gce_tags - prefix: tag - - key: status | lower - prefix: status - - key: image - prefix: '' - separator: '' - plugin: google.cloud.gcp_compute - retrieve_image_info: true - use_contrib_script_compatible_sanitization: true - - -Microsoft Azure Resource Manager ---------------------------------- - -.. index:: - pair: inventories; Microsoft Azure Resource Manager - pair: inventories; azure - pair: inventory plugins; azure - -:: - - conditional_groups: - azure: true - default_host_filters: [] - fail_on_template_errors: false - hostvar_expressions: - computer_name: name - private_ip: private_ipv4_addresses[0] if private_ipv4_addresses else None - provisioning_state: provisioning_state | title - public_ip: public_ipv4_addresses[0] if public_ipv4_addresses else None - public_ip_id: public_ip_id if public_ip_id is defined else None - public_ip_name: public_ip_name if public_ip_name is defined else None - tags: tags if tags else None - type: resource_type - keyed_groups: - - key: location - prefix: '' - separator: '' - - key: tags.keys() | list if tags else [] - prefix: '' - separator: '' - - key: security_group - prefix: '' - separator: '' - - key: resource_group - prefix: '' - separator: '' - - key: os_disk.operating_system_type - prefix: '' - separator: '' - - key: dict(tags.keys() | map("regex_replace", "^(.*)$", "\1_") | list | zip(tags.values() | list)) if tags else [] - prefix: '' - separator: '' - plain_host_names: true - plugin: azure.azcollection.azure_rm - use_contrib_script_compatible_sanitization: true - -VMware vCenter ---------------- - -.. index:: - pair: inventories; VMware vCenter - pair: inventories; vmware - pair: inventory plugins; vmware - -:: - - compose: - ansible_host: guest.ipAddress - ansible_ssh_host: guest.ipAddress - ansible_uuid: 99999999 | random | to_uuid - availablefield: availableField - configissue: configIssue - configstatus: configStatus - customvalue: customValue - effectiverole: effectiveRole - guestheartbeatstatus: guestHeartbeatStatus - layoutex: layoutEx - overallstatus: overallStatus - parentvapp: parentVApp - recenttask: recentTask - resourcepool: resourcePool - rootsnapshot: rootSnapshot - triggeredalarmstate: triggeredAlarmState - filters: - - runtime.powerState == "poweredOn" - keyed_groups: - - key: config.guestId - prefix: '' - separator: '' - - key: '"templates" if config.template else "guests"' - prefix: '' - separator: '' - plugin: community.vmware.vmware_vm_inventory - properties: - - availableField - - configIssue - - configStatus - - customValue - - datastore - - effectiveRole - - guestHeartbeatStatus - - layout - - layoutEx - - name - - network - - overallStatus - - parentVApp - - permission - - recentTask - - resourcePool - - rootSnapshot - - snapshot - - triggeredAlarmState - - value - - capability - - config - - guest - - runtime - - storage - - summary - strict: false - with_nested_properties: true - - -.. _ir_plugin_satellite: - -Red Hat Satellite 6 ---------------------- - -.. index:: - pair: inventories; Red Hat Satellite 6 - pair: inventories; satellite - pair: inventory plugins; satellite - -:: - - group_prefix: foreman_ - keyed_groups: - - key: foreman['environment_name'] | lower | regex_replace(' ', '') | regex_replace('[^A-Za-z0-9_]', '_') | regex_replace('none', '') - prefix: foreman_environment_ - separator: '' - - key: foreman['location_name'] | lower | regex_replace(' ', '') | regex_replace('[^A-Za-z0-9_]', '_') - prefix: foreman_location_ - separator: '' - - key: foreman['organization_name'] | lower | regex_replace(' ', '') | regex_replace('[^A-Za-z0-9_]', '_') - prefix: foreman_organization_ - separator: '' - - key: foreman['content_facet_attributes']['lifecycle_environment_name'] | lower | regex_replace(' ', '') | regex_replace('[^A-Za-z0-9_]', '_') - prefix: foreman_lifecycle_environment_ - separator: '' - - key: foreman['content_facet_attributes']['content_view_name'] | lower | regex_replace(' ', '') | regex_replace('[^A-Za-z0-9_]', '_') - prefix: foreman_content_view_ - separator: '' - legacy_hostvars: true - plugin: theforeman.foreman.foreman - validate_certs: false - want_facts: true - want_hostcollections: false - want_params: true - - -OpenStack ----------- - -.. index:: - pair: inventories; OpenStack - pair: inventories; OpenStack - pair: inventory plugins; OpenStack - -:: - - expand_hostvars: true - fail_on_errors: true - inventory_hostname: uuid - plugin: openstack.cloud.openstack - - -Red Hat Virtualization ------------------------ - -.. index:: - pair: inventories; Red Hat Virtualization - pair: inventories; rhv - pair: inventory plugins; rhv - -:: - - compose: - ansible_host: (devices.values() | list)[0][0] if devices else None - keyed_groups: - - key: cluster - prefix: cluster - separator: _ - - key: status - prefix: status - separator: _ - - key: tags - prefix: tag - separator: _ - ovirt_hostname_preference: - - name - - fqdn - ovirt_insecure: false - plugin: ovirt.ovirt.ovirt - - -Red Hat Ansible Automation Platform ----------------------------------------- - -.. index:: - pair: inventories; Red Hat Ansible Automation Platform - pair: inventory plugins; Red Hat Ansible Automation Platform - -:: - - include_metadata: true - inventory_id: <inventory_id or url_quoted_named_url> - plugin: awx.awx.tower - validate_certs: <true or false>
\ No newline at end of file |
