From b5817e78db1b47cf85e8c0dfec48540da83e19b3 Mon Sep 17 00:00:00 2001 From: djdanielsson Date: Mon, 28 Oct 2024 02:20:16 +0000 Subject: [PATCH] Apply automatic changes --- collections/aap_utilities/aap_backup.md | 51 +++ collections/aap_utilities/aap_certs.md | 79 ++++ collections/aap_utilities/aap_ocp_install.md | 135 ++++++ collections/aap_utilities/aap_remove.md | 55 +++ collections/aap_utilities/aap_restore.md | 50 ++ .../aap_utilities/aap_setup_download.md | 56 +++ .../aap_utilities/aap_setup_install.md | 132 ++++++ .../aap_utilities/aap_setup_prepare.md | 139 ++++++ collections/aap_utilities/git_ssh_setup.md | 43 ++ collections/aap_utilities/index.md | 8 + collections/aap_utilities/kerberos.md | 103 +++++ .../ah_configuration/ansible_config.md | 115 +++++ collections/ah_configuration/collection.md | 117 +++++ .../ah_configuration/collection_remote.md | 125 +++++ .../ah_configuration/collection_repository.md | 131 ++++++ .../collection_repository_sync.md | 104 +++++ collections/ah_configuration/dispatch.md | 111 +++++ collections/ah_configuration/ee_image.md | 106 +++++ collections/ah_configuration/ee_namespace.md | 105 +++++ collections/ah_configuration/ee_registry.md | 109 +++++ .../ah_configuration/ee_registry_index.md | 105 +++++ .../ah_configuration/ee_registry_sync.md | 105 +++++ collections/ah_configuration/ee_repository.md | 107 +++++ .../ah_configuration/ee_repository_sync.md | 105 +++++ collections/ah_configuration/group.md | 113 +++++ collections/ah_configuration/group_roles.md | 154 +++++++ collections/ah_configuration/index.md | 8 + collections/ah_configuration/namespace.md | 127 ++++++ collections/ah_configuration/offline_sync.md | 102 +++++ collections/ah_configuration/publish.md | 111 +++++ collections/ah_configuration/repository.md | 130 ++++++ .../ah_configuration/repository_sync.md | 106 +++++ collections/ah_configuration/role.md | 127 ++++++ collections/ah_configuration/user.md | 115 +++++ .../ansible_config.md | 115 +++++ .../controller_ad_hoc_command.md | 108 +++++ .../controller_ad_hoc_command_cancel.md | 99 ++++ .../controller_applications.md | 149 ++++++ .../controller_bulk_host_create.md | 143 ++++++ .../controller_bulk_job_launch.md | 141 ++++++ .../controller_credential_input_sources.md | 174 +++++++ .../controller_credential_types.md | 250 ++++++++++ .../controller_credentials.md | 176 +++++++ .../controller_execution_environments.md | 138 ++++++ .../controller_host_groups.md | 179 ++++++++ .../controller_hosts.md | 165 +++++++ .../controller_instance_groups.md | 130 ++++++ .../controller_instances.md | 129 ++++++ .../controller_inventories.md | 184 ++++++++ .../controller_inventory_source_update.md | 121 +++++ .../controller_inventory_sources.md | 197 ++++++++ .../controller_job_launch.md | 110 +++++ .../controller_job_templates.md | 305 +++++++++++++ .../controller_jobs_cancel.md | 90 ++++ .../controller_labels.md | 127 ++++++ .../controller_license.md | 151 ++++++ .../controller_notification_templates.md | 203 +++++++++ .../controller_organizations.md | 194 ++++++++ .../controller_project_update.md | 130 ++++++ .../controller_projects.md | 179 ++++++++ .../controller_roles.md | 196 ++++++++ .../controller_schedules.md | 171 +++++++ .../controller_settings.md | 154 +++++++ .../controller_teams.md | 113 +++++ .../controller_users.md | 147 ++++++ .../controller_workflow_job_templates.md | 429 ++++++++++++++++++ .../controller_workflow_launch.md | 98 ++++ .../controller_configuration/dispatch.md | 47 ++ .../eda_controller_tokens.md | 101 +++++ .../eda_credentials.md | 106 +++++ .../eda_decision_environments.md | 106 +++++ .../controller_configuration/eda_projects.md | 107 +++++ .../eda_rulebook_activations.md | 121 +++++ .../controller_configuration/eda_users.md | 113 +++++ .../gateway_applications.md | 123 +++++ .../gateway_authenticator_maps.md | 163 +++++++ .../gateway_authenticators.md | 132 ++++++ .../gateway_http_ports.md | 113 +++++ .../gateway_organizations.md | 118 +++++ .../gateway_role_user_assignments.md | 111 +++++ .../gateway_routes.md | 134 ++++++ .../gateway_service_clusters.md | 115 +++++ .../gateway_service_keys.md | 116 +++++ .../gateway_service_nodes.md | 126 +++++ .../gateway_services.md | 136 ++++++ .../gateway_settings.md | 84 ++++ .../controller_configuration/gateway_teams.md | 116 +++++ .../controller_configuration/gateway_users.md | 114 +++++ .../controller_configuration/global_vars.md | 49 ++ .../hub_collection.md | 120 +++++ .../hub_collection_remote.md | 127 ++++++ .../hub_collection_repository.md | 133 ++++++ .../hub_collection_repository_sync.md | 106 +++++ .../controller_configuration/hub_ee_image.md | 108 +++++ .../hub_ee_registry.md | 111 +++++ .../hub_ee_registry_index.md | 107 +++++ .../hub_ee_registry_sync.md | 107 +++++ .../hub_ee_repository.md | 109 +++++ .../hub_ee_repository_sync.md | 107 +++++ .../controller_configuration/hub_group.md | 115 +++++ .../hub_group_roles.md | 156 +++++++ .../controller_configuration/hub_namespace.md | 129 ++++++ .../controller_configuration/hub_publish.md | 113 +++++ .../controller_configuration/hub_role.md | 127 ++++++ .../controller_configuration/hub_user.md | 117 +++++ collections/controller_configuration/index.md | 8 + .../meta_dependency_check.md | 17 + collections/eda_configuration/credential.md | 105 +++++ .../eda_configuration/decision_environment.md | 103 +++++ collections/eda_configuration/dispatch.md | 92 ++++ collections/eda_configuration/index.md | 8 + collections/eda_configuration/project.md | 105 +++++ collections/eda_configuration/project_sync.md | 105 +++++ .../eda_configuration/rulebook_activation.md | 113 +++++ collections/eda_configuration/user.md | 111 +++++ collections/eda_configuration/user_token.md | 101 +++++ collections/ee_utilities/ee_builder.md | 262 +++++++++++ collections/ee_utilities/index.md | 8 + .../ee_utilities/virtualenv_migrate.md | 105 +++++ 119 files changed, 14370 insertions(+) create mode 100644 collections/aap_utilities/aap_backup.md create mode 100644 collections/aap_utilities/aap_certs.md create mode 100644 collections/aap_utilities/aap_ocp_install.md create mode 100644 collections/aap_utilities/aap_remove.md create mode 100644 collections/aap_utilities/aap_restore.md create mode 100644 collections/aap_utilities/aap_setup_download.md create mode 100644 collections/aap_utilities/aap_setup_install.md create mode 100644 collections/aap_utilities/aap_setup_prepare.md create mode 100644 collections/aap_utilities/git_ssh_setup.md create mode 100644 collections/aap_utilities/index.md create mode 100644 collections/aap_utilities/kerberos.md create mode 100644 collections/ah_configuration/ansible_config.md create mode 100644 collections/ah_configuration/collection.md create mode 100644 collections/ah_configuration/collection_remote.md create mode 100644 collections/ah_configuration/collection_repository.md create mode 100644 collections/ah_configuration/collection_repository_sync.md create mode 100644 collections/ah_configuration/dispatch.md create mode 100644 collections/ah_configuration/ee_image.md create mode 100644 collections/ah_configuration/ee_namespace.md create mode 100644 collections/ah_configuration/ee_registry.md create mode 100644 collections/ah_configuration/ee_registry_index.md create mode 100644 collections/ah_configuration/ee_registry_sync.md create mode 100644 collections/ah_configuration/ee_repository.md create mode 100644 collections/ah_configuration/ee_repository_sync.md create mode 100644 collections/ah_configuration/group.md create mode 100644 collections/ah_configuration/group_roles.md create mode 100644 collections/ah_configuration/index.md create mode 100644 collections/ah_configuration/namespace.md create mode 100644 collections/ah_configuration/offline_sync.md create mode 100644 collections/ah_configuration/publish.md create mode 100644 collections/ah_configuration/repository.md create mode 100644 collections/ah_configuration/repository_sync.md create mode 100644 collections/ah_configuration/role.md create mode 100644 collections/ah_configuration/user.md create mode 100644 collections/controller_configuration/ansible_config.md create mode 100644 collections/controller_configuration/controller_ad_hoc_command.md create mode 100644 collections/controller_configuration/controller_ad_hoc_command_cancel.md create mode 100644 collections/controller_configuration/controller_applications.md create mode 100644 collections/controller_configuration/controller_bulk_host_create.md create mode 100644 collections/controller_configuration/controller_bulk_job_launch.md create mode 100644 collections/controller_configuration/controller_credential_input_sources.md create mode 100644 collections/controller_configuration/controller_credential_types.md create mode 100644 collections/controller_configuration/controller_credentials.md create mode 100644 collections/controller_configuration/controller_execution_environments.md create mode 100644 collections/controller_configuration/controller_host_groups.md create mode 100644 collections/controller_configuration/controller_hosts.md create mode 100644 collections/controller_configuration/controller_instance_groups.md create mode 100644 collections/controller_configuration/controller_instances.md create mode 100644 collections/controller_configuration/controller_inventories.md create mode 100644 collections/controller_configuration/controller_inventory_source_update.md create mode 100644 collections/controller_configuration/controller_inventory_sources.md create mode 100644 collections/controller_configuration/controller_job_launch.md create mode 100644 collections/controller_configuration/controller_job_templates.md create mode 100644 collections/controller_configuration/controller_jobs_cancel.md create mode 100644 collections/controller_configuration/controller_labels.md create mode 100644 collections/controller_configuration/controller_license.md create mode 100644 collections/controller_configuration/controller_notification_templates.md create mode 100644 collections/controller_configuration/controller_organizations.md create mode 100644 collections/controller_configuration/controller_project_update.md create mode 100644 collections/controller_configuration/controller_projects.md create mode 100644 collections/controller_configuration/controller_roles.md create mode 100644 collections/controller_configuration/controller_schedules.md create mode 100644 collections/controller_configuration/controller_settings.md create mode 100644 collections/controller_configuration/controller_teams.md create mode 100644 collections/controller_configuration/controller_users.md create mode 100644 collections/controller_configuration/controller_workflow_job_templates.md create mode 100644 collections/controller_configuration/controller_workflow_launch.md create mode 100644 collections/controller_configuration/dispatch.md create mode 100644 collections/controller_configuration/eda_controller_tokens.md create mode 100644 collections/controller_configuration/eda_credentials.md create mode 100644 collections/controller_configuration/eda_decision_environments.md create mode 100644 collections/controller_configuration/eda_projects.md create mode 100644 collections/controller_configuration/eda_rulebook_activations.md create mode 100644 collections/controller_configuration/eda_users.md create mode 100644 collections/controller_configuration/gateway_applications.md create mode 100644 collections/controller_configuration/gateway_authenticator_maps.md create mode 100644 collections/controller_configuration/gateway_authenticators.md create mode 100644 collections/controller_configuration/gateway_http_ports.md create mode 100644 collections/controller_configuration/gateway_organizations.md create mode 100644 collections/controller_configuration/gateway_role_user_assignments.md create mode 100644 collections/controller_configuration/gateway_routes.md create mode 100644 collections/controller_configuration/gateway_service_clusters.md create mode 100644 collections/controller_configuration/gateway_service_keys.md create mode 100644 collections/controller_configuration/gateway_service_nodes.md create mode 100644 collections/controller_configuration/gateway_services.md create mode 100644 collections/controller_configuration/gateway_settings.md create mode 100644 collections/controller_configuration/gateway_teams.md create mode 100644 collections/controller_configuration/gateway_users.md create mode 100644 collections/controller_configuration/global_vars.md create mode 100644 collections/controller_configuration/hub_collection.md create mode 100644 collections/controller_configuration/hub_collection_remote.md create mode 100644 collections/controller_configuration/hub_collection_repository.md create mode 100644 collections/controller_configuration/hub_collection_repository_sync.md create mode 100644 collections/controller_configuration/hub_ee_image.md create mode 100644 collections/controller_configuration/hub_ee_registry.md create mode 100644 collections/controller_configuration/hub_ee_registry_index.md create mode 100644 collections/controller_configuration/hub_ee_registry_sync.md create mode 100644 collections/controller_configuration/hub_ee_repository.md create mode 100644 collections/controller_configuration/hub_ee_repository_sync.md create mode 100644 collections/controller_configuration/hub_group.md create mode 100644 collections/controller_configuration/hub_group_roles.md create mode 100644 collections/controller_configuration/hub_namespace.md create mode 100644 collections/controller_configuration/hub_publish.md create mode 100644 collections/controller_configuration/hub_role.md create mode 100644 collections/controller_configuration/hub_user.md create mode 100644 collections/controller_configuration/index.md create mode 100644 collections/controller_configuration/meta_dependency_check.md create mode 100644 collections/eda_configuration/credential.md create mode 100644 collections/eda_configuration/decision_environment.md create mode 100644 collections/eda_configuration/dispatch.md create mode 100644 collections/eda_configuration/index.md create mode 100644 collections/eda_configuration/project.md create mode 100644 collections/eda_configuration/project_sync.md create mode 100644 collections/eda_configuration/rulebook_activation.md create mode 100644 collections/eda_configuration/user.md create mode 100644 collections/eda_configuration/user_token.md create mode 100644 collections/ee_utilities/ee_builder.md create mode 100644 collections/ee_utilities/index.md create mode 100644 collections/ee_utilities/virtualenv_migrate.md diff --git a/collections/aap_utilities/aap_backup.md b/collections/aap_utilities/aap_backup.md new file mode 100644 index 0000000..07f71ec --- /dev/null +++ b/collections/aap_utilities/aap_backup.md @@ -0,0 +1,51 @@ +--- +layout: default +title: aap_backup +parent: infra.aap_utilities +--- + +# infra.aap\_utilities.backup + +Ansible role to backup Ansible Automation Platform. + +## Requirements + +None + +## Role Variables + +Available variables are listed below, along with default values defined (see defaults/main.yml) + +```yaml +aap_setup_prep_setup_dir: # Must be set, though if the aap_setup_prepare role has been run prior, a fact will be set. +aap_backup_dest: "/root" +``` + +## Example Playbook + +The following playbook and accompanying vars file containing the defined seed objects can be invoked in the following manner. + +```sh +ansible-playbook playbook.yml -e @aap_vars.yml controller +``` + +```yaml +# Playbook to backup Automation controller + +- name: Backup Automation controller + hosts: localhost + become: true + vars: + aap_setup_prep_setup_dir: /root/ansible-automation-platform-installer/ + aap_backup_dest: /aap_backups/ + roles: + - infra.aap_utilities.aap_backup +``` + +## License + +[GPLv3+0](https://github.com/redhat-cop/aap_utilities#licensing) + +## Author Information + +Sean Sullivan diff --git a/collections/aap_utilities/aap_certs.md b/collections/aap_utilities/aap_certs.md new file mode 100644 index 0000000..0f6a75e --- /dev/null +++ b/collections/aap_utilities/aap_certs.md @@ -0,0 +1,79 @@ +--- +layout: default +title: aap_certs +parent: infra.aap_utilities +--- + +# infra.aap\_utilities.aap\_certs + +Ansible role to install SSL certificates for AAP automation controller and/or automation hub and/or EDA controller. + +Certificates are only installed if the underlying destination directory does already exist, +this allows to point the role at all servers in the cluster. + +Note it is also possible to deploy the certificates at install time with the proper inventory variables. + +## Requirements + +The certificates must have been created with certificate and key. + +## Role Variables + +Available variables are listed below, along with default values defined (see [defaults](defaults/main.yml)). + +Variables to point at the source certificates and keys for controller, +respective automation hub. +They are undefined by default which means that no certificate is installed: + +```yaml +aap_certs_controller_ssl_cert: "{{ playbook_dir }}/tower.cert" +aap_certs_controller_ssl_key: "{{ playbook_dir }}/tower.key" +aap_certs_autohub_ssl_cert: "{{ playbook_dir }}/pulp.cert" +aap_certs_autohub_ssl_key: "{{ playbook_dir }}/pulp.key" +aap_certs_eda_ssl_cert: "{{ playbook_dir }}/server.cert" +aap_certs_eda_ssl_key: "{{ playbook_dir }}/server.key" + +``` + +The content of the certificates and keys can also be set rather than specifying a file. +This is useful when you're using a secrets backend like HashiCorp Vault. +**Note that these are each mutually exclusive with the variables above.** + +```yaml + +``` + +The following variable defines if the old certificates/keys should be backed-up: + +```yaml +aap_certs_create_backup: false +``` + +## Example Playbook + +The following playbook and accompanying vars file containing the defined seed objects can be invoked in the following manner. + +```sh +ansible-playbook playbook.yml -e @aap_vars.yml +``` + +```yaml +- name: Install AAP certificates + hosts: aap_servers + become: true + vars: + aap_certs_controller_ssl_cert: "{{ playbook_dir }}/tower.cert" + aap_certs_controller_ssl_key: "{{ playbook_dir }}/tower.key" + aap_certs_autohub_ssl_cert: "" + aap_certs_autohub_ssl_key: "" + roles: + - infra.aap_utilities.aap_certs +``` + +## License + +[GPLv3+0](https://github.com/redhat-cop/aap_utilities#licensing) + +## Author Information + +Tom Page diff --git a/collections/aap_utilities/aap_ocp_install.md b/collections/aap_utilities/aap_ocp_install.md new file mode 100644 index 0000000..79e0c9d --- /dev/null +++ b/collections/aap_utilities/aap_ocp_install.md @@ -0,0 +1,135 @@ +--- +layout: default +title: aap_ocp_install +parent: infra.aap_utilities +--- + +# infra.aap_utilities.aap_ocp_install + +A role to install Ansible Automation Platform (AAP) 2.x on OpenShift using the operator. + +## Requirements + +This role requires the `kubernetes` (version 12.0.0 or later) Python module. +In addition the kubernetes.core and redhat.openshift Ansible collections are required. + +## Role Variables + +A description of the settable variables for this role should go here, including any variables that are in defaults/main.yml, vars/main.yml, and any variables that can/should be set via parameters to the role. Any variables that are read from other roles and/or the global scope (ie. hostvars, group vars, etc.) should be mentioned here as well. + +| Variable Name | Required | Default Value | Description | +| aap_ocp_install_namespace | Yes | None | Namespace to create operator, controller, and hub in | +| aap_ocp_install_create_namespace | No | None | Create the Namespace for the operator, controller and hub. Valid values are: `true`, `false` | +| aap_ocp_install_namespace_manifest_overrides | No | None | Namespace to create operator, controller, and hub in | +| aap_ocp_install_connection | Yes | None | Dictionary containing keys defined in the `connection variables table` | +| aap_ocp_install_operator | Yes* | None | YAML Manifest to override the generated operator `Namespace` resource | +| aap_ocp_install_controller | Yes* | None | Dictionary containing keys defined in the `controller variables table` | +| aap_ocp_install_hub | Yes* | None | Dictionary containing keys defined in the `hub variables table` | + +\* Variable and required keys must be defined when the type of tag is specified (e.g. `--tags controller` requires the aap_ocp_install_controller variable be defined). +If the variable is omitted the corresponding component will not be installed (e.g. if only aap_ocp_install_hub variable is defined then the operator and controller installation will be skipped) + +### aap_ocp_install_connection keys + +| Key Name | Required | Default Value | Description | +| host | Yes | None | OCP cluster to create the AAP objects in | +| username | Yes* | None | Username to use for authenticating with OCP | +| password | Yes* | None | Password to use for authenticating with OCP | +| api_key | Yes* | None | OCP API Token | +| validate_certs | | None | Validate SSL certificates. Valid values are: `true`, `false` | + +\* Either `api_key` or `username` and `password` can be specified. + +### aap_ocp_install_operator keys + +| Key Name | Required | Default Value | Description | +| channel | Yes | None | Channel to subscribe (e.g. stable-2.2 or stable-2.2-cluster-scoped) | +| approval | | Automatic | Update approval method. Valid values are Automatic or Manual. | +| operatorgroup_create | | true | Create the `OperatorGroup` for the Operator | +| operatorgroup_manifest_overrides | | | YAML Manifest to override the generated `OperatorGroup` resource | +| subscription_manifest_overrides | | | YAML Manifest to override the generated `Subscription` resource | + +> ℹ️ **NOTE** +> +> When `approval` is set to `Manual` the operator will be installed with `Automatic` approval and then after installation the approval will be updated to Manual. + +### aap_ocp_install_controller keys + +| Key Name | Required | Default Value | Description | +| instance_name | Yes | None | Name of the controller instance to create | +| namespace | | None | Name of the namespace to create the controller instance in. If not specified `aap_ocp_install_namespace` will be used. | +| namespace_manifest_overrides | | None | YAML Manifest to override the generated `Namespace` resource for the controller if the `namespace` key is defined | +| admin_user | | admin | Username to use for the admin account | +| replicas | | 1 | How many replicas to create. | +| garbage_collect_secrets | | false | Whether or not to remove secrets upon instance removal | +| image_pull_policy | | IfNotPresent | The image pull policy | +| create_preload_data | | true | Whether or not to preload data upon instance creation | +| projects_persistence | | false | Whether or not the /var/lib/projects directory will be persistent | +| projects_storage_size | | 8Gi | Size of /var/lib/projects persistent volume claim (PVC) | +| link_text | | Automation Controller () | Text used for creating the OCP application link | +| controller_manifest_overrides | | None | YAML Manifest to override the generated `AutomationController` resource link | +| consolelink_manifest_overrides | | None | YAML Manifest to override the generated `ConsoleLink` resource | + +### aap_ocp_install_hub keys + +| Key Name | Required | Default Value | Description | +| instance_name | Yes | None | Name of the hub instance to create | +| namespace | | None | Name of the namespace to create the hub instance in. If not specified `aap_ocp_install_namespace` will be used. | +| namespace_manifest_overrides | | None | YAML Manifest to override the generated `Namespace` resource for the hub if the `namespace` key is defined | +| link_text | | Automation Hub () | Text used for creating the OCP application link | +| hub_manifest_overrides | | None | YAML Manifest to override the generated `AutomationHub` resource | +| consolelink_manifest_overrides | | None | YAML Manifest to override the generated `ConsoleLink` resource | + +### aap_ocp_install_eda keys + +| Key Name | Required | Default Value | Description | +| instance_name | Yes | None | Name of the EDA instance to create | +| namespace | | None | Name of the namespace to create the EDA instance in. If not specified `aap_ocp_install_namespace` will be used. | +| namespace_manifest_overrides | | None | YAML Manifest to override the generated `Namespace` resource for the EDA if the `namespace` key is defined | +| link_text | | EDA Controller () | Text used for creating the OCP application link | +| eda_manifest_overrides | | None | YAML Manifest to override the generated `EDA` resource | +| consolelink_manifest_overrides | | None | YAML Manifest to override the generated `ConsoleLink` resource | + +## Dependencies + +This role depends on the redhat.openshift and kubernetes.core collections. + +## Example Playbook + +Including an example of how to use your role (for instance, with variables passed in as parameters) is always nice for users too: + +```yml +- name: Install AAP on OCP playbook + hosts: localhost + gather_facts: false + + vars: + aap_ocp_install_connection: + host: "https://api.crc.testing:6443" + username: kubeadmin + password: + validate_certs: false + aap_ocp_install_namespace: aap-test + aap_ocp_install_operator: + channel: "stable-2.2" + aap_ocp_install_controller: + instance_name: automationcontroller + aap_ocp_install_hub: + instance_name: automationhub + aap_ocp_install_eda: + instance_name: edacontroller + + roles: + - infra.aap_utilities.aap_ocp_install +... +``` + +## License + +[GPLv3+0](https://github.com/redhat-cop/aap_utilities#licensing) + +## Author Information + +* Brant Evans +* Derek Waters +* Andrew Block diff --git a/collections/aap_utilities/aap_remove.md b/collections/aap_utilities/aap_remove.md new file mode 100644 index 0000000..25c9ed0 --- /dev/null +++ b/collections/aap_utilities/aap_remove.md @@ -0,0 +1,55 @@ +--- +layout: default +title: aap_remove +parent: infra.aap_utilities +--- + +# infra.aap_utilities.aap_remove + +Ansible role to remove instances of AAP. + +## Requirements + +None + +## Role Variables + +Available variables are listed below, along with default values defined (see defaults/main.yml) + +```yaml +# Role Vars +aap_remove_controller: false +aap_remove_ah: false +``` + +The above are used to determine whether to remove Controller or Automation Hub from the node. +We recommend setting a host vars or simply using separate plays for each host which determines which of these vars to set true. +An example is below. + +## Example Playbook + +```yaml +# Playbook to install AAP2 + +- name: Remove Ansible Controller + hosts: controller + vars: + aap_remove_controller: true + roles: + - infra.aap_utilities.aap_remove + +- name: Remove Ansible Automation Hub + hosts: ah + vars: + aap_remove_ah: true + roles: + - infra.aap_utilities.aap_remove +``` + +## License + +[GPLv3+0](https://github.com/redhat-cop/aap_utilities#licensing) + +## Author Information + +Tom Page diff --git a/collections/aap_utilities/aap_restore.md b/collections/aap_utilities/aap_restore.md new file mode 100644 index 0000000..8808fd2 --- /dev/null +++ b/collections/aap_utilities/aap_restore.md @@ -0,0 +1,50 @@ +--- +layout: default +title: aap_restore +parent: infra.aap_utilities +--- + +# infra.aap\_utilities.aap\_restore + +Ansible role to restore a backup of Ansible Automation Platform. + +## Requirements + +None + +## Role Variables + +Available variables are listed below, along with default values defined (see defaults/main.yml) + +```yaml +# Role Vars +aap_setup_working_dir: # Must be set, though if the aap_setup_prepare role has been run prior, a fact will be set. +aap_restore_location: "{{ aap_setup_working_dir }}/{{ aap_restore_file }}" +``` + +## Example Playbook + +The following playbook and accompanying vars file containing the defined seed objects can be invoked in the following manner. + +```sh +ansible-playbook playbook.yml -e @aap_vars.yml +``` + +```yaml +- name: Restore AAP + hosts: localhost + become: true + vars: + aap_setup_working_dir: /root/ansible-automation-platform-installer/ + aap_restore_location: "{{playbook_dir}}/aap-backup-latest.tar.gz" + roles: + - infra.aap_utilities.aap_restore +``` + +## License + +[GPLv3+0](https://github.com/redhat-cop/aap_utilities#licensing) + +## Author Information + +Sean Sullivan diff --git a/collections/aap_utilities/aap_setup_download.md b/collections/aap_utilities/aap_setup_download.md new file mode 100644 index 0000000..ae7002e --- /dev/null +++ b/collections/aap_utilities/aap_setup_download.md @@ -0,0 +1,56 @@ +--- +layout: default +title: aap_setup_download +parent: infra.aap_utilities +--- + +# infra.aap_utilities.aap\_setup\_download + +A role to download the latest z-version of the AAP setup tarball for a given minor version (e.g. 2.1 at time of writing). + +Shamelessly adapted from [Red Hat Ansible Automation Platform 2: Automating the Installer Download and publishing as a Content View in Satellite](https://www.redhat.com/en/blog/automating-installation-ansible-automation-platform-ansible-and-satellite). + +## Requirements + +You will need a Red Hat Ansible Automation Platform (AAP, hence the name) subscription. +Once this is a given, you will be able to create yourself an offline token at [https://access.redhat.com/management/api/](https://access.redhat.com/management/api/) (see [Getting started with Red Hat APIs](https://access.redhat.com/articles/3626371) for details). + +## Role Variables + +The following input variables are required: + +* `aap_setup_down_offline_token` contains your offline token as described in the requirements. +It has no default value and _must_ be defined. +* `aap_setup_down_version` defines the minor version to download (e.g. `2.1`) +The default is the latest version available at time of writing. +* `aap_setup_down_dest_dir` is the directory to where you want to download the tarball. +It is by default the working directory `aap_setup_working_dir` also used by other roles of the collection, or ultimately `/var/tmp`. +* `aap_setup_down_type` can be either `setup`, `setup-bundle`, `containerized-setup`, depending which flavour of the tarball you want to download. +* `aap_setup_rhel_version` defines the major RHEL version being used (currently 8 or 9). If you are gathering facts you possibly don't need to specify this as the role will attempt to work out the value required though you will if AAP will be installed on machines on a different OS than the installer will run on. Otherwise the default is 8. +* `aap_setup_containerized` if set to `true` the role will download the the containerized installer. +* `aap_setup_arch` define the processor architecture of the installer. Default to "x86_64" + +The full path of the downloaded file is stored in the fact `aap_setup_down_installer_file` so that it can be used for extraction. + +## Dependencies + +None. + +## Example Playbook + +Combined with the role `aap_setup_prepare`, the following code will download and prepare the installation directory: + +```yaml +- hosts: installationserver + roles: + - { role: infra.aap_utilities.aap_setup_download } + - { role: infra.aap_utilities.aap_setup_prepare } +``` + +## License + +[GPLv3+0](https://github.com/redhat-cop/aap_utilities#licensing) + +## Author Information + +Eric Lavarde , Red Hat Consulting, Principal Architect diff --git a/collections/aap_utilities/aap_setup_install.md b/collections/aap_utilities/aap_setup_install.md new file mode 100644 index 0000000..e63db1e --- /dev/null +++ b/collections/aap_utilities/aap_setup_install.md @@ -0,0 +1,132 @@ +--- +layout: default +title: aap_setup_install +parent: infra.aap_utilities +--- + +# infra.aap_utilities.aap\_setup\_install + +A role to install AAP 2.x, installing pre-requisites, unpacking the installation tarball and (optionally) writing the necessary inventory file. + +## Requirements + +* The installation package must have been extracted +* The necessary inventory must have been written + +## Role Variables + +The following input variables are available: + +|Variable Name|Default Value|Required|Description|Example| +|`aap_setup_inst_setup_dir`|"`{{ aap_setup_prep_setup_dir }}`"|no|absolute path where to find the extracted installation tarball on the remote host, note that `aap_setup_prep_setup_dir` is a fact set by the role `aap_setup_prepare`|'/var/tmp/myinstaller'| +|`aap_setup_inst_inventory`|"`inventory`"|no|path to the inventory file/directory to be used for the installation, the path can be absolute or relative to the previous directory|'/etc/ansible/inventory'| +|`aap_setup_inst_extra_vars`|`{}`|no|dictionary of extra vars to use when calling setup.sh|see [defaults/main.yml](defaults/main.yml)| +|`aap_setup_inst_extra_vars_files`|`{}`|no|List of files to be applied as extra vars when calling setup.sh|see [defaults/main.yml](defaults/main.yml)| +|`controller_hostname/username/password/validate_certs`|none|see below|hostname and credentials of the installed controller, necessary to test previous installation|see the 'redhat\_cop.controller\_configuration' collection| +|`ah_hostname/username/password/validate_certs`|none|see below|hostname and credentials of the installed automation hub, necessary to test previous installation|see the 'redhat\_cop.ah\_configuration' collection| +|`aap_setup_inst_force`|false|no|a boolean deciding if the installation should proceed even if the controller and the automation hub are already installed|see [defaults/main.yml](defaults/main.yml)| +|`aap_setup_inst_log_dir`|none|no|directory where setup.sh stores the log file|'/tmp/'| +|`aap_setup_inst_containerized`|"`{{ aap_setup_containerized }}`"|no|if true will run a containerized AAP install|see [defaults/main.yml](defaults/main.yml)| + +Note that the `controller_` and `ah_` variables are only required if the variable `aap_setup_inst_force` is _not_ true _and_ if the respective service is due to be installed. + +## Dependencies + +* `aap_setup_download`, in the same collection, can be used to download the tarball automatically. +* `aap_setup_prepare`, in the same collection, can be used to extract the tarball and write the inventory + +## Example Playbook + +```yaml +- name: download and install AAP from the bastion + hosts: bastion + gather_facts: false + become: false + tags: aap_installation + roles: + - infra.aap_utilities.aap_setup_download + - infra.aap_utilities.aap_setup_prepare + - infra.aap_utilities.aap_setup_install +``` + +Note that this only works without root access if the bastion host isn't part of the future cluster, +and if the RPM pre-requisites have been pre-installed. +Else change to `become: true`. + +## Example Inventory Variables + +```yaml +aap_setup_down_type: "setup-bundle" +aap_setup_rhel_version: 8 + +aap_setup_prep_inv_nodes: # a dictionary of dictionaries! + automationcontroller: + ansible-ctrl.example.com: + automationhub: + ansible-hub.example.com: + automationedacontroller: + ansible-eda.example.com: + database: + database.example.com: # If using an already existing DB, remove this group/node + # and adapt accordingly the following database related values + execution_nodes: + execution-1.example.com: + execution-2.example.com: + +aap_setup_prep_inv_vars: + automationcontroller: # denotes the automation controller nodes as hybrid nodes (both controller and execution) + peers: execution_nodes + node_type: hybrid + + execution_nodes: + node_type: execution + + all: + ansible_user: ansible + ansible_become: true + admin_password: changeme # admin password for Automation Controller UI + pg_host: 'database.example.com' + pg_port: '5432' + + pg_database: 'awx' + pg_username: 'awx' + pg_password: changeme + pg_sslmode: 'prefer' # set to 'verify-full' for client-side enforced SSL + + registry_url: 'registry.redhat.io' + receptor_listener_port: 27199 + + automationhub_admin_password: changeme # admin password for PAH UI + automationhub_pg_host: 'database.example.com' + automationhub_pg_port: '5432' + + automationhub_pg_database: 'automationhub' + automationhub_pg_username: 'automationhub' + automationhub_pg_password: changeme + automationhub_pg_sslmode: 'prefer' + automationhub_main_url: https://hub.example.com #url, not hostname + automationhub_require_content_approval: False + automationhub_enable_unauthenticated_collection_access: True + + automationhub_ssl_validate_certs: False + + automationedacontroller_admin_password: 'password' # Admin password for EDA UI + automationedacontroller_pg_host: 'controller.aap24.local' + automationedacontroller_pg_port: '5432' + automationedacontroller_pg_database: 'automationedacontroller' + automationedacontroller_pg_username: 'automationedacontroller' + automationedacontroller_pg_password: 'password' + +aap_setup_prep_inv_secrets: + all: + registry_username: changeme + registry_password: changeme +``` + +## License + +[GPLv3+0](https://github.com/redhat-cop/aap_utilities#licensing) + +## Author Information + +Eric Lavarde diff --git a/collections/aap_utilities/aap_setup_prepare.md b/collections/aap_utilities/aap_setup_prepare.md new file mode 100644 index 0000000..b036c94 --- /dev/null +++ b/collections/aap_utilities/aap_setup_prepare.md @@ -0,0 +1,139 @@ +--- +layout: default +title: aap_setup_prepare +parent: infra.aap_utilities +--- + +# infra.aap_utilities.aap\_setup\_prepare + +A role to prepare the installation of AAP 2.x, installing pre-requisites, +unpacking the installation tarball and (optionally) writing the necessary inventory file. + +## Requirements + +* The installer tarball must be available, by default downloaded with the `aap_setup_download` role. +* The (RPM) pre-requisites must have been installed, or root access must be given. + +## Role Variables + +The following input variables are available: + +|Variable Name|Default Value|Required|Description|Example| +|`aap_setup_prep_installer_file`|"`{{ aap_setup_down_installer_file }}`"|no|absolute path where to find the tarball on the remote host, or URL http(s), note that `aap_setup_down_installer_file` is a fact set by the role `aap_setup_download`|`'https://myhost/myinstaller.tar.gz'` or `'/var/tmp/myinstaller.tar.gz'`| +|`aap_setup_prep_working_dir`|"`{{ aap_setup_working_dir \| default('/var/tmp') }}`"|no|absolute path to a working directory, note that `aap_setup_working_dir` is used by other roles in the collection|'/srv/workdir'| +|`aap_setup_prep_process_template`|true|no|shall the inventory be generated by the role?|false| +|`aap_setup_prep_inv_nodes`|none|yes|a dictionary of dictionaries, the first level key is the inventory group name, the 2nd level key is the hostname with the value being its inventory host variables in INI-format|see [defaults/main.yml](defaults/main.yml)| +|`aap_setup_prep_inv_vars`|{}|see below|a dictionary of dictionaries, the first level key is the inventory group name, the 2nd level key is the variable name with the value being the variable's value|see [defaults/main.yml](defaults/main.yml)| +|`aap_setup_prep_inv_secrets`|{}|see below|a dictionary of dictionaries, the first level key is the inventory group name, the 2nd level key is the variable name with the value being the variable's value|see [defaults/main.yml](defaults/main.yml)| +|`aap_setup_prep_containerized`|"`{{ aap_setup_containerized }}`"|no|will the setup prep be for a containerized install|see [defaults/main.yml](defaults/main.yml)| + +Some notes about the inventory variables and secrets: + +* both values will be combined (the secrets overwriting the variables) and used to generate the installation inventory, so that secret variables can be defined separately for example in a vault. +* even if formally both variables don't need to be defined, you'll get a viable inventory only if you define some keys/variables at least in the group `all`. +By convention the [defaults/main.yml](defaults/main.yml) contains all possible variables as comments, the variables commented out _twice_ are truly optional. + +## Dependencies + +* `aap_setup_download`, in the same collection, can be used to download the tarball automatically. + +## Example Playbook + +```yaml +- name: download and install AAP from the bastion + hosts: bastion + gather_facts: false + become: false + tags: aap_installation + + vars_files: + - inventory_vars/variables.yml + roles: + - infra.aap_utilities.aap_setup_download + - infra.aap_utilities.aap_setup_prepare + - infra.aap_utilities.aap_setup_install +``` + +Note that this only works without root access if the bastion host isn't part of the future cluster, +and if the RPM pre-requisites have been pre-installed. +Else change to `become: true`. + +## Example Inventory Variables + +```yaml +aap_setup_down_type: "setup-bundle" +aap_setup_rhel_version: 8 + +aap_setup_prep_inv_nodes: # a dictionary of dictionaries! + automationcontroller: + ansible-ctrl.example.com: + automationhub: + ansible-hub.example.com: + automationedacontroller: + ansible-eda.example.com: + database: + database.example.com: # If using an already existing DB, remove this group/node + # and adapt accordingly the following database related values + execution_nodes: + execution-1.example.com: + execution-2.example.com: + +aap_setup_prep_inv_vars: + automationcontroller: # denotes the automation controller nodes as hybrid nodes (controller and execution) + peers: execution_nodes + node_type: hybrid + + execution_nodes: + node_type: execution + + all: + ansible_user: ansible + ansible_become: true + admin_password: changeme # admin password for Automation Controller UI + pg_host: 'database.example.com' + pg_port: '5432' + + pg_database: 'awx' + pg_username: 'awx' + pg_password: changeme + pg_sslmode: 'prefer' # set to 'verify-full' for client-side enforced SSL + + registry_url: 'registry.redhat.io' + receptor_listener_port: 27199 + + automationhub_admin_password: changeme # admin password for PAH UI + automationhub_pg_host: 'database.example.com' + automationhub_pg_port: '5432' + + automationhub_pg_database: 'automationhub' + automationhub_pg_username: 'automationhub' + automationhub_pg_password: changeme + automationhub_pg_sslmode: 'prefer' + automationhub_main_url: https://hub.example.com #url, not hostname + automationhub_require_content_approval: False + automationhub_enable_unauthenticated_collection_access: True + + automationhub_ssl_validate_certs: False + + automationedacontroller_admin_password: 'password' # Admin password for EDA UI + automationedacontroller_pg_host: 'controller.aap24.local' + automationedacontroller_pg_port: '5432' + automationedacontroller_pg_database: 'automationedacontroller' + automationedacontroller_pg_username: 'automationedacontroller' + automationedacontroller_pg_password: 'password' + + sso_console_admin_password: '' + +aap_setup_prep_inv_secrets: + all: + registry_username: changeme + registry_password: changeme +``` + +## License + +[GPLv3+0](https://github.com/redhat-cop/aap_utilities#licensing) + +## Author Information + +Eric Lavarde diff --git a/collections/aap_utilities/git_ssh_setup.md b/collections/aap_utilities/git_ssh_setup.md new file mode 100644 index 0000000..66c854e --- /dev/null +++ b/collections/aap_utilities/git_ssh_setup.md @@ -0,0 +1,43 @@ +--- +layout: default +title: git_ssh_setup +parent: infra.aap_utilities +--- + +# infra.aap\_utilities.git\_ssh\_setup + +Creates a minimal Git server which can be used over SSH. It isn't meant as a full blown Git server, +but just for demonstration and learning purposes, and can be installed directly on the AAP servers. + +## Requirements + +The only pre-requisite is SSH itself, without which Ansible wouldn't work anyway. + +## Role Variables + +See the [defaults file](defaults/main.yml). + +## Dependencies + +None. + +## Example Playbook + +The following snippet, using the defaults, will create two Git repos under the git's user home folder, +which can be used (cloned and written) by the Ansible user: + +```yaml +- hosts: controller.example.com + roles: + - infra.aap_utilities.git_ssh_setup +``` + +We've assumed that it will be created directly on the Controller server for demonstration purposes. + +## License + +[GPLv3+0](https://github.com/redhat-cop/aap_utilities#licensing) + +## Author Information + +Create an [issue at GitHub](https://github.com/redhat-cop/aap_utilities/issues) if you want to contact us. diff --git a/collections/aap_utilities/index.md b/collections/aap_utilities/index.md new file mode 100644 index 0000000..3adac9c --- /dev/null +++ b/collections/aap_utilities/index.md @@ -0,0 +1,8 @@ +--- +layout: default +title: infra.aap_utilities +has_children: true +nav_order: 5 +--- + +# aap_utilities \ No newline at end of file diff --git a/collections/aap_utilities/kerberos.md b/collections/aap_utilities/kerberos.md new file mode 100644 index 0000000..ec90e08 --- /dev/null +++ b/collections/aap_utilities/kerberos.md @@ -0,0 +1,103 @@ +--- +layout: default +title: kerberos +parent: infra.aap_utilities +--- + +# infra.aap\_utilities.kerberos + +## Description + +An Ansible role to setup authentication to a windows domain server with kerberos. + +## Requirements + +This role installs all required packages in order to facilitate authentication. + +## Variables + +|Name|Required|Default Value|Type|Description| +|`krb_realms`|yes|N/A|List of Dictionaries|Used for storing the realm(domain) name and its domain controllers. A single domain controller can be specified if that is the only available option, but more than one is preferable. See example usage below.| +|`krb_default_realm`|no|undefined|string|If a default realm(domain) is required to be specified this can be set. Otherwise it remains unset in the krb5.conf.| +|`krb_dns_lookup_realm`|yes|"false"|string|Whether or not to lookup DNS via realm.| +|`krb_dns_lookup_kdc`|no|"true"|string|Indicate whether DNS SRV records should be used to locate the KDCs and other servers for a realm.| +|`krb_ticket_lifetime`|yes|"24h"|string|Sets the default lifetime for initial ticket requests.| +|`krb_renew_lifetime`|yes|"7d"|string|Kerberos renewable ticket lifetime.| +|`krb_forwardable`|yes|"true"|string|Forwardable kerberos tickets.| +|`krb_rdns`|yes|"false"|string|Whether or not to use rdns.| + +### Example use of krb_realms + +Note that the first listed item in each listed realm's dc_fqdns list will be set as the realm's admin_server. + +```yaml +krb_realms: + - name: "MYDOMAIN.COM" + dc_fqdns: + - "foo1.bar.mydomain.com" + - "foo2.bar.mydomain.com" + - name: "YOURDOMAIN.COM" + dc_fqdns: + - "ad1.yourdomain.com" + - "ad2.yourdomain.com" +``` + +## Dependencies + +There are no dependencies required for this role + +The dependencies for Linux, are all installed by this role. + +For Windows 2k12 and 2k16 the powershell script in files needs to be run in through a privledged PowerShell. + +For Windows 2k8 the folllowing is required for some ansible modules to work: + +* Server 2008 R2 Service pack 1 +* Powershell v4. via Windows Management Framework 4.0 build 6.1 + +To check what version of powershell is installed, run the following in powershell: + +```PowerShell +$PSVersionTable.PSVersion +``` + +## Tags + +If you would like to skip the check of EPEL and python-pip installation, +you can skip the tag `prerequisites` with `--skip-tags prerequisites` option at run-time. + +## HTTP/HTTPS Proxy Settings + +If you require a proxy server to reach external repositories located on the internet, +ensure that you have set them either on the server running the playbook, or in the playbook including the role. + +## Example Playbook + +```yaml +- hosts: controllers +# If you need proxy settings to install packages from the internet: +# The following 3 lines are optional + environment: + http_proxy: "yourproxyurl:andport" + https_proxy: "yourproxyurl:andport" + roles: + - role: infra.aap_utilities.kerberos + krb_default_realm: MYDOMAIN.COM + krb_realms: + - name: "MYDOMAIN.COM" + dc_fqdns: + - "foo1.bar.mydomain.com" + - "foo2.bar.mydomain.com" + - name: "YOURDOMAIN.COM" + dc_fqdns: + - "ad1.yourdomain.com" + - "ad2.yourdomain.com" +``` + +## License + +[GPLv3+0](https://github.com/redhat-cop/aap_utilities#licensing) + +## Author + +[Andrew J. Huffman](https://github.com/ahuffman) diff --git a/collections/ah_configuration/ansible_config.md b/collections/ah_configuration/ansible_config.md new file mode 100644 index 0000000..7476f0c --- /dev/null +++ b/collections/ah_configuration/ansible_config.md @@ -0,0 +1,115 @@ +--- +layout: default +title: ansible_config +parent: infra.ah_configuration +--- + +# galaxy.galaxy.ansible_config + +## Description + +An Ansible Role to create ansible.cfg files based on your Automation Hub servers + +## Requirements + +ansible-galaxy collection install -r tests/collections/requirements.yml to be installed +Currently: + awx.awx + +## Variables + +|Variable Name|Default Value|Required|Description|Example| +|`ansible_config_mode`|'0644'|no|str|The permissions the resulting ansible config file or directory should have.| +|`ansible_config_owner`|""|no|str|The owner the resulting ansible config file or directory should have.| +|`ansible_config_group`|""|no|str|The group the resulting ansible config file or directory should have.| +|`ah_configuration_working_dir`|"/var/tmp"|no|path|Location to render the ansible config file to.| +|`automation_hub_list`|`[]`|no|list|A list of Automation hubs and galaxies to put in the ansible config, see below for details.| +|`ansible_config_list`|`[{"header":"galaxy","keypairs":[{"key":"ignore_certs","value":"{{ not (ah_validate_certs \| bool) }}"}]}]`|no|list|A set of ansible config settings, a default is set, but can be overridden, see below for details.| +|`ah_token`|""|no|Tower Admin User's token on the Automation Hub Server. This should be stored in an Ansible Vault at or elsewhere and called from a parent playbook.|| +|`ah_path_prefix`|`galaxy`|no|Tower Admin User's token on the Automation Hub Server. This should be stored in an Ansible Vault at or elsewhere and called from a parent playbook.|| + +### Secure Logging Variables + +The following Variables compliment each other. +If Both variables are not set, secure logging defaults to false. +The role defaults to False as normally the ansible config task does not by default include sensitive information, we highly recommend the use of ansible vault for passwords and tokens. +ah_configuration_ansible_config_secure_logging defaults to the value of ah_configuration_secure_logging if it is not explicitly called. This allows for secure logging to be toggled for the entire suite of automation hub configuration roles with a single variable, or for the user to selectively use it. + +|Variable Name|Default Value|Required|Description| +|`ah_configuration_ansible_config_secure_logging`|`False`|no|Whether or not to include the sensitive ansible config role tasks in the log. Set this value to `True` if you will be providing your sensitive values from elsewhere.| +|`ah_configuration_secure_logging`|`False`|no|This variable enables secure logging as well, but is shared across multiple roles, see above.| + +## Data Structures + +### automation_hub_list + +|Variable Name|Default Value|Required|Type|Description| +|`name`|""|yes|str|Name of the Automation Hub or Galaxy Server.| +|`url`|""|yes|str|URL to the Automation Hub or Galaxy Server| +|`auth_url`|""|no|str|URL to the authentication for Automation Hub or Galaxy Server| +|`token`|""|no|str|Automation Hub or Galaxy Server token.| + +### ansible_config_list + +|Variable Name|Default Value|Required|Type|Description| +|`header`|""|yes|str|Header of the section that contains keypairs.| +|`keypairs`|`[]`|no|list|List key value pairs for settings in the ansible.cfg.| + +### ansible_config_list[].keypairs + +|Variable Name|Default Value|Required|Type|Description| +|`key`|""|yes|str|Key for entry under this header.| +|`value`|""|yes|str|Value for entry for the corresponding key.| + +### Standard Project Data Structure + +#### Yaml Example + +```yaml +ansible_config_list: + - header: galaxy + keypairs: + - key: ignore_certs + value: "{{ not (ah_validate_certs | bool) }}" + - key: server_list + value: "{{ automation_hub_list }}" + +automation_hub_list: + - name: automation_hub + url: "{{ah_host}}/api/automation-hub/content/0000001-synclist/" + auth_url: https://sso.redhat.com/auth/realms/redhat-external/protocol/openid-connect/token + token: changeme +``` + +## Playbook Examples + +### Standard Role Usage + +```yaml +- name: Set up Ansible Configuration for usage with PAH + hosts: localhost + connection: local + gather_facts: false + vars: + ah_validate_certs: false + # Define following vars here, or in ah_configs/ah_auth.yml + # ah_host: ansible-ah-web-svc-test-project.example.com + # ah_token: changeme + pre_tasks: + - name: Include vars from ah_configs directory + ansible.builtin.include_vars: + dir: ./vars + extensions: ["yml"] + tags: + - always + roles: + - ../../ansible_config +``` + +## License + +[GPLv3+](https://github.com/ansible/galaxy_collection#licensing) + +## Author + +[Sean Sullivan](https://github.com/sean-m-sullivan/) diff --git a/collections/ah_configuration/collection.md b/collections/ah_configuration/collection.md new file mode 100644 index 0000000..d4590e0 --- /dev/null +++ b/collections/ah_configuration/collection.md @@ -0,0 +1,117 @@ +--- +layout: default +title: collection +parent: infra.ah_configuration +--- + +# galaxy.galaxy.collection + +## Description + +An Ansible Role to update, or destroy Automation Hub Collections. + +## Variables + +|Variable Name|Default Value|Required|Description|Example| +|`ah_host`|""|yes|URL to the Automation Hub or Galaxy Server. (alias: `ah_hostname`)|127.0.0.1| +|`ah_username`|""|yes|Admin User on the Automation Hub or Galaxy Server.|| +|`ah_password`|""|yes|Automation Hub Admin User's password on the Automation Hub Server. This should be stored in an Ansible Vault at vars/tower-secrets.yml or elsewhere and called from a parent playbook.|| +|`ah_validate_certs`|`true`|no|Whether or not to validate the Ansible Automation Hub Server's SSL certificate.|| +|`ah_request_timeout`|`10`|no|Specify the timeout Ansible should use in requests to the Galaxy or Automation Hub host.|| +|`ah_path_prefix`|""|no|API path used to access the api. Either galaxy, automation-hub, or custom|| +|`ah_configuration_async_dir`|`null`|no|Sets the directory to write the results file for async tasks. The default value is set to `null` which uses the Ansible Default of `/root/.ansible_async/`.|| +|`ah_collections`|`see below`|yes|Data structure describing your collections, described below.|| + +These are the sub options for the vars `ah_collections` which are dictionaries with the options you want. See examples for details. +|Variable Name|Default Value|Required|Description|Example| +|`namespace`|""|yes|Namespace name. Must be lower case containing only alphanumeric characters and underscores.|"awx"| +|`name`|""|yes|Collection name. Must be lower case containing only alphanumeric characters and underscores.|| +|`version`|""|no|Collection Version. Must be lower case containing only alphanumeric characters and underscores. If not provided and 'auto_approve' true, will be derived from the path.|| +|`path`|""|no|Collection artifact file path.|| +|`wait`|"true"|no|Waits for the collection to be uploaded|| +|`auto_approve`|"true"|no|Approves a collection and requires version to be set.|| +|`timeout`|"true"||Maximum time to wait for the collection approval|| +|`interval`|"true"|10|Interval at which approval is checked|| +|`overwrite_existing`|"false"|no|Overwrites an existing collection and requires version to be set.|| +|`state`|"present"|no|Desired state of the resource|| + +The `ah_configuration_async_dir` variable sets the directory to write the results file for async tasks. +The default value is set to `null` which uses the Ansible Default of `/root/.ansible_async/`. + +### Asynchronous Retry Variables + +The following Variables set asynchronous retries for the role. +If neither of the retries or delay or retries are set, they will default to their respective defaults. +This allows for all items to be created, then checked that the task finishes successfully. +This also speeds up the overall role. + +|Variable Name|Default Value|Required|Description| +|`ah_configuration_async_timeout`|1000|no|This variable sets the async timeout for the role globally.| +|`ah_configuration_collection_async_timeout`|`ah_configuration_async_timeout`|no|This variable sets the async timeout for the role.| +|`ah_configuration_async_retries`|50|no|This variable sets the number of retries to attempt for the role globally.| +|`ah_configuration_collection_async_retries`|`ah_configuration_async_retries`|no|This variable sets the number of retries to attempt for the role.| +|`ah_configuration_async_delay`|1|no|This sets the delay between retries for the role globally.| +|`ah_configuration_collection_async_delay`|`ah_configuration_async_delay`|no|This sets the delay between retries for the role.| + +### Secure Logging Variables + +The following Variables compliment each other. +If Both variables are not set, secure logging defaults to false. +The role defaults to False as normally the add repository task does not include sensitive information. +ah_configuration_repository_secure_logging defaults to the value of ah_configuration_secure_logging if it is not explicitly called. This allows for secure logging to be toggled for the entire suite of automation hub configuration roles with a single variable, or for the user to selectively use it. + +|Variable Name|Default Value|Required|Description| +|`ah_configuration_collection_secure_logging`|`False`|no|Whether or not to include the sensitive collection role tasks in the log. Set this value to `True` if you will be providing your sensitive values from elsewhere.| +|`ah_configuration_secure_logging`|`False`|no|This variable enables secure logging as well, but is shared across multiple roles, see above.| + +## Data Structure + +### Standard Project Data Structure + +#### Yaml Example + +```yaml +ah_collections: + - namespace: 'awx' + name: 'awx' + path: /var/tmp/collections/awx_awx-15.0.0.tar.gz + state: present + + - namespace: test_collection + name: test + version: 4.1.2 + state: absent +``` + +## Playbook Examples + +### Standard Role Usage + +```yaml +- name: Add collection + hosts: localhost + connection: local + gather_facts: false + vars: + ah_validate_certs: false + # Define following vars here, or in ah_configs/ah_auth.yml + # ah_host: ansible-ah-web-svc-test-project.example.com + # ah_token: changeme + pre_tasks: + - name: Include vars from ah_configs directory + ansible.builtin.include_vars: + dir: ./vars + extensions: ["yml"] + tags: + - always + roles: + - ../../collection +``` + +## License + +[GPLv3+](https://github.com/ansible/galaxy_collection#licensing) + +## Author + +[Inderpal Tiwana](https://github.com/inderpaltiwana/) diff --git a/collections/ah_configuration/collection_remote.md b/collections/ah_configuration/collection_remote.md new file mode 100644 index 0000000..3a08b4c --- /dev/null +++ b/collections/ah_configuration/collection_remote.md @@ -0,0 +1,125 @@ +--- +layout: default +title: collection_remote +parent: infra.ah_configuration +--- + +# collection_remote + +## Description + +An Ansible Role to create a Collection Remote Repository. + +## Variables + +|Variable Name|Default Value|Required|Description|Example| +|`ah_host`|""|yes|URL to the Automation Hub or Galaxy Server. (alias: `ah_hostname`)|127.0.0.1| +|`ah_username`|""|yes|Admin User on the Automation Hub or Galaxy Server.|| +|`ah_password`|""|yes|Automation Hub Admin User's password on the Automation Hub Server. This should be stored in an Ansible Vault at vars/tower-secrets.yml or elsewhere and called from a parent playbook.|| +|`ah_validate_certs`|`true`|no|Whether or not to validate the Ansible Automation Hub Server's SSL certificate.|| +|`ah_request_timeout`|`10`|no|Specify the timeout Ansible should use in requests to the Galaxy or Automation Hub host.|| +|`ah_path_prefix`|""|no|API path used to access the api. Either galaxy, automation-hub, or custom|| +|`ah_configuration_async_dir`|`null`|no|Sets the directory to write the results file for async tasks. The default value is set to `null` which uses the Ansible Default of `/root/.ansible_async/`.|| +|`ah_collection_remotes`|`see below`|yes|Data structure describing your collection remote repository, described below.|| + +The `ah_configuration_async_dir` variable sets the directory to write the results file for async tasks. +The default value is set to `null` which uses the Ansible Default of `/root/.ansible_async/`. + +### Secure Logging Variables + +The following Variables compliment each other. +If Both variables are not set, secure logging defaults to false. +The role defaults to False as normally the add repository task does not include sensitive information. +ah_configuration_repository_secure_logging defaults to the value of ah_configuration_secure_logging if it is not explicitly called. This allows for secure logging to be toggled for the entire suite of automation hub configuration roles with a single variable, or for the user to selectively use it. + +|Variable Name|Default Value|Required|Description| +|`ah_configuration_collection_remote_secure_logging`|`False`|no|Whether or not to include the sensitive Namespace role tasks in the log. Set this value to `True` if you will be providing your sensitive values from elsewhere.| +|`ah_configuration_secure_logging`|`False`|no|This variable enables secure logging as well, but is shared across multiple roles, see above.| + +### Asynchronous Retry Variables + +The following Variables set asynchronous retries for the role. +If neither of the retries or delay or retries are set, they will default to their respective defaults. +This allows for all items to be created, then checked that the task finishes successfully. +This also speeds up the overall role. + +|Variable Name|Default Value|Required|Description| +|`ah_configuration_async_timeout`|1000|no|This variable sets the async timeout for the role globally.| +|`ah_configuration_collection_remote_async_timeout`|`ah_configuration_async_timeout`|no|This variable sets the async timeout for the role.| +|`ah_configuration_async_retries`|50|no|This variable sets the number of retries to attempt for the role globally.| +|`ah_configuration_collection_remote_async_retries`|`ah_configuration_async_retries`|no|This variable sets the number of retries to attempt for the role.| +|`ah_configuration_async_delay`|1|no|This sets the delay between retries for the role globally.| +|`ah_configuration_collection_remote_async_delay`|`ah_configuration_async_delay`|no|This sets the delay between retries for the role.| + +## Data Structure + +### Collection Remote Variables + +|Variable Name|Default Value|Required|Description|Example| +|`name`|``|yes| Repository name. Probably one of community, validated, or rh-certified|| +|`url`|`https://cloud.redhat.com/api/automation-hub/`|no|(`ah_repository_certified`)Remote URL for the repository.|`https://console.redhat.com/api/automation-hub/content/`| +|`url`|`https://galaxy.ansible.com/api/`|no|(`ah_repository_community`)Remote URL for the repository.|| +|`auth_url`|`https://sso.redhat.com/auth/realms/redhat-external/protocol/openid-connect/token`|no|(`ah_repository_certified`)Remote URL for the repository authentication if separate.|| +|`token`|``|no|Token to authenticate to the remote repository.|| +|`policy`|`immediate`|no|The policy to use when downloading content. Can be one of `immediate`, `When syncing, download all metadata and content now.`.|| +|`requirements`|``|no|Requirements, a list of collections in [requirements file format](https://docs.ansible.com/ansible/latest/collections_guide/collections_installing.html#install-multiple-collections-with-a-requirements-file) to limit thedownload from remote. This will only download provided collections. This is only the list under collections. See examples for usage.|| +|`requirements_file`|``|no|A yaml requirements file to download from remote. In requirements file format. Exclusive with `requirements` || +|`username`|``|no|Username to authenticate to the remote repository.|| +|`password`|``|no|Password to authenticate to the remote repository.|| +|`tls_validation`|`True`|no|Whether to use TLS validation against the remote repository|True| +|`client_key`|``|no|A PEM encoded private key file used for authentication|| +|`client_cert`|``|no|A PEM encoded client certificate used for authentication|| +|`ca_cert`|``|no|A PEM encoded CA certificate used for authentication|| +|`client_key_path`|``|no|Path to a PEM encoded private key file used for authentication|| +|`client_cert_path`|``|no|Path to a PEM encoded client certificate used for authentication|| +|`ca_cert_path`|``|no|Path to a PEM encoded CA certificate used for authentication|| +|`download_concurrency`|`10`|no| Number of concurrent collections to download.|| +|`max_retries`|`0`|no|Retries to use when running sync. Default is 0 which does not limit.|| +|`rate_limit`|`8`|no|Limits total download rate in requests per second.|| +|`signed_only`|`False`|no|Only download signed collections|False| +|`sync_dependencies`|`True`|no|Whether to download dependencies when syncing collections.|False| +|`proxy_url`|``|no|The URL for the proxy. Defaults to global `proxy_url` variable.|| +|`proxy_username`|``|no|The username for the proxy authentication. Defaults to global `proxy_username` variable.|| +|`proxy_password`|``|no|The password for the proxy authentication. Defaults to global `proxy_password` variable.|| +|`state`|`present`|no|Desired state of the collection_remote. Either `present` or `absent`.|| + +### Standard Project Data Structure + +#### Yaml Example + +```yaml +ah_collection_remotes: + - name: community-infra + url: https://beta-galaxy.ansible.com/ + requirements: + - name: infra.ee_utilities + - name: infra.controller_configuration +``` + +## Playbook Examples + +### Standard Role Usage + +```yaml +- name: Add repository to Automation Hub + hosts: localhost + connection: local + gather_facts: false + vars: + ah_validate_certs: false + # Define following vars here, or in ah_configs/ah_auth.yml + # ah_host: ansible-ah-web-svc-test-project.example.com + pre_tasks: + - name: Include vars from ah_configs directory + ansible.builtin.include_vars: + dir: ./vars + extensions: ["yml"] + tags: + - always + roles: + - ../../collection_remote +``` + +## License + +[GPLv3+](https://github.com/ansible/galaxy_collection#licensing) diff --git a/collections/ah_configuration/collection_repository.md b/collections/ah_configuration/collection_repository.md new file mode 100644 index 0000000..eed4125 --- /dev/null +++ b/collections/ah_configuration/collection_repository.md @@ -0,0 +1,131 @@ +--- +layout: default +title: collection_repository +parent: infra.ah_configuration +--- + +# collection_repository + +## Description + +An Ansible Role to create a Collection Repository. + +## Variables + +|Variable Name|Default Value|Required|Description|Example| +|`ah_host`|""|yes|URL to the Automation Hub or Galaxy Server. (alias: `ah_hostname`)|127.0.0.1| +|`ah_username`|""|yes|Admin User on the Automation Hub or Galaxy Server.|| +|`ah_password`|""|yes|Automation Hub Admin User's password on the Automation Hub Server. This should be stored in an Ansible Vault at vars/tower-secrets.yml or elsewhere and called from a parent playbook.|| +|`ah_validate_certs`|`true`|no|Whether or not to validate the Ansible Automation Hub Server's SSL certificate.|| +|`ah_request_timeout`|`10`|no|Specify the timeout Ansible should use in requests to the Galaxy or Automation Hub host.|| +|`ah_path_prefix`|""|no|API path used to access the api. Either galaxy, automation-hub, or custom|| +|`ah_configuration_async_dir`|`null`|no|Sets the directory to write the results file for async tasks. The default value is set to `null` which uses the Ansible Default of `/root/.ansible_async/`.|| +|`ah_collection_repositories`|`see below`|yes|Data structure describing your collection remote repository, described below.|| + +The `ah_configuration_async_dir` variable sets the directory to write the results file for async tasks. +The default value is set to `null` which uses the Ansible Default of `/root/.ansible_async/`. + +### Secure Logging Variables + +The following Variables compliment each other. +If Both variables are not set, secure logging defaults to false. +The role defaults to False as normally the add repository task does not include sensitive information. +ah_configuration_repository_secure_logging defaults to the value of ah_configuration_secure_logging if it is not explicitly called. This allows for secure logging to be toggled for the entire suite of automation hub configuration roles with a single variable, or for the user to selectively use it. + +|Variable Name|Default Value|Required|Description| +|`ah_configuration_collection_repository_secure_logging`|`False`|no|Whether or not to include the sensitive Namespace role tasks in the log. Set this value to `True` if you will be providing your sensitive values from elsewhere.| +|`ah_configuration_secure_logging`|`False`|no|This variable enables secure logging as well, but is shared across multiple roles, see above.| + +### Asynchronous Retry Variables + +The following Variables set asynchronous retries for the role. +If neither of the retries or delay or retries are set, they will default to their respective defaults. +This allows for all items to be created, then checked that the task finishes successfully. +This also speeds up the overall role. + +|Variable Name|Default Value|Required|Description| +|`ah_configuration_async_timeout`|1000|no|This variable sets the async timeout for the role globally.| +|`ah_configuration_collection_repository_async_timeout`|`ah_configuration_async_timeout`|no|This variable sets the async timeout for the role.| +|`ah_configuration_async_retries`|50|no|This variable sets the number of retries to attempt for the role globally.| +|`ah_configuration_collection_repository_async_retries`|`ah_configuration_async_retries`|no|This variable sets the number of retries to attempt for the role.| +|`ah_configuration_async_delay`|1|no|This sets the delay between retries for the role globally.| +|`ah_configuration_collection_repository_async_delay`|`ah_configuration_async_delay`|no|This sets the delay between retries for the role.| + +## Data Structure + +### Collection Repository Variables + +|Variable Name|Default Value|Required|Type|Description| +|`name`|""|yes|str| Collection Repository name. Probably one of community, validated, rh-certified, or one you have created.| +|`description`|""|no|str|Description to use for the Collection Repository.| +|`retain_repo_versions`|0|no|int|Retain X versions of the Collection repository. Default is 0 which retains all versions.| +|`pulp_labels`|""|no|dict|Pipeline and search options for the collection repository. See additional options below for details.| +|`distribution`|""|no|dict|Distribution options for the collection repository. See additional options below for details. Most users will leave this blank| +|`private`|""|no|boolean|Make the Collection repository private.| +|`remote`|""|no|str|Remote repository name. This is used if the collections use a remote source.| +|`update`|`false`|no|bool|Wait for the Collection repository to finish syncing before returning.| +|`wait`|`true`|no|bool|Wait for the Collection repository to finish syncing before returning.| +|`interval`|1.0|no|float|The interval to request an update from Automation Hub.| +|`timeout`|""|no|int|If waiting for the project to update this will abort after this amount of seconds.| +|`state`|`present`|no|str|Desired state of the collection repository. Either `present` or `absent`.| + +#### Additional Option Variables + +```yaml +pulp_labels: + pipeline: "approved" + hide_from_search: "" +distribution: + name: "foobar" + state: present +``` + +|Variable Name|Default Value|Required|Type|Description| +|`pipeline`|""|no|str|Description to use for the Collection Repository.| +|`hide_from_search`|""|no|str|Pipeline and search options for the collection repository.| +|`name`|""|no|dict|Distribution name to use for this collection repository. Will default to repository name if not provided.| +|`state`|`absent`|no|str|Desired state of the distribution. Either `present` or `absent`.| + +### Standard Project Data Structure + +#### Yaml Example + +```yaml +ah_collection_repositories: + - name: "foobar" + description: "description of foobar repository" + pulp_labels: + pipeline: "approved" + distribution: + name: "foobar" + state: present + remote: community +``` + +## Playbook Examples + +### Standard Role Usage + +```yaml +- name: Add repository to Automation Hub + hosts: localhost + connection: local + gather_facts: false + vars: + ah_validate_certs: false + # Define following vars here, or in ah_configs/ah_auth.yml + # ah_host: ansible-ah-web-svc-test-project.example.com + pre_tasks: + - name: Include vars from ah_configs directory + ansible.builtin.include_vars: + dir: ./vars + extensions: ["yml"] + tags: + - always + roles: + - ../../collection_repository +``` + +## License + +[GPLv3+](https://github.com/ansible/galaxy_collection#licensing) diff --git a/collections/ah_configuration/collection_repository_sync.md b/collections/ah_configuration/collection_repository_sync.md new file mode 100644 index 0000000..bfc5288 --- /dev/null +++ b/collections/ah_configuration/collection_repository_sync.md @@ -0,0 +1,104 @@ +--- +layout: default +title: collection_repository_sync +parent: infra.ah_configuration +--- + +# collection_repository_sync + +## Description + +An Ansible Role to sync a Collection Repository. + +## Variables + +|Variable Name|Default Value|Required|Description|Example| +|`ah_host`|""|yes|URL to the Automation Hub or Galaxy Server. (alias: `ah_hostname`)|127.0.0.1| +|`ah_username`|""|yes|Admin User on the Automation Hub or Galaxy Server.|| +|`ah_password`|""|yes|Automation Hub Admin User's password on the Automation Hub Server. This should be stored in an Ansible Vault at vars/tower-secrets.yml or elsewhere and called from a parent playbook.|| +|`ah_validate_certs`|`true`|no|Whether or not to validate the Ansible Automation Hub Server's SSL certificate.|| +|`ah_request_timeout`|`10`|no|Specify the timeout Ansible should use in requests to the Galaxy or Automation Hub host.|| +|`ah_path_prefix`|""|no|API path used to access the api. Either galaxy, automation-hub, or custom|| +|`ah_configuration_async_dir`|`null`|no|Sets the directory to write the results file for async tasks. The default value is set to `null` which uses the Ansible Default of `/root/.ansible_async/`.|| +|`ah_collection_repositories`|`see below`|yes|Data structure describing your collection remote repository, described below.|| + +The `ah_configuration_async_dir` variable sets the directory to write the results file for async tasks. +The default value is set to `null` which uses the Ansible Default of `/root/.ansible_async/`. + +### Secure Logging Variables + +The following Variables compliment each other. +If Both variables are not set, secure logging defaults to false. +The role defaults to False as normally the add repository task does not include sensitive information. +ah_configuration_repository_secure_logging defaults to the value of ah_configuration_secure_logging if it is not explicitly called. This allows for secure logging to be toggled for the entire suite of automation hub configuration roles with a single variable, or for the user to selectively use it. + +|Variable Name|Default Value|Required|Description| +|`ah_configuration_collection_repository_sync_secure_logging`|`False`|no|Whether or not to include the sensitive Namespace role tasks in the log. Set this value to `True` if you will be providing your sensitive values from elsewhere.| +|`ah_configuration_secure_logging`|`False`|no|This variable enables secure logging as well, but is shared across multiple roles, see above.| + +### Asynchronous Retry Variables + +The following Variables set asynchronous retries for the role. +If neither of the retries or delay or retries are set, they will default to their respective defaults. +This allows for all items to be created, then checked that the task finishes successfully. +This also speeds up the overall role. + +|Variable Name|Default Value|Required|Description| +|`ah_configuration_async_timeout`|1000|no|This variable sets the async timeout for the role globally.| +|`ah_configuration_collection_repository_sync_async_timeout`|`ah_configuration_async_timeout`|no|This variable sets the async timeout for the role.| +|`ah_configuration_async_retries`|50|no|This variable sets the number of retries to attempt for the role globally.| +|`ah_configuration_collection_repository_sync_async_retries`|`ah_configuration_async_retries`|no|This variable sets the number of retries to attempt for the role.| +|`ah_configuration_async_delay`|1|no|This sets the delay between retries for the role globally.| +|`ah_configuration_collection_repository_sync_async_delay`|`ah_configuration_async_delay`|no|This sets the delay between retries for the role.| + +## Data Structure + +### Collection Repository Variables + +|Variable Name|Default Value|Required|Type|Description| +|`name`|""|yes|str| Collection Repository name. Probably one of community, validated, rh-certified, or one you have created.| +|`wait`|`true`|no|bool|Wait for the Collection repository to finish syncing before returning.| +|`interval`|1.0|no|float|The interval to request an update from Automation Hub.| +|`timeout`|""|no|int|If waiting for the repository to update this will abort after this amount of seconds.| +|`state`|`present`|no|str|Desired state of the collection repository. Either `present` or `absent`.| + +### Standard Project Data Structure + +#### Yaml Example + +```yaml +ah_collection_repositories: + - name: rh-certified + wait: false + - name: community + wait: true + timeout: 60 +``` + +## Playbook Examples + +### Standard Role Usage + +```yaml +- name: Sync repository to Automation Hub + hosts: localhost + connection: local + gather_facts: false + vars: + ah_validate_certs: false + # Define following vars here, or in ah_configs/ah_auth.yml + # ah_host: ansible-ah-web-svc-test-project.example.com + pre_tasks: + - name: Include vars from ah_configs directory + ansible.builtin.include_vars: + dir: ./vars + extensions: ["yml"] + tags: + - always + roles: + - ../../collection_repository_sync +``` + +## License + +[GPLv3+](https://github.com/ansible/galaxy_collection#licensing) diff --git a/collections/ah_configuration/dispatch.md b/collections/ah_configuration/dispatch.md new file mode 100644 index 0000000..ef16391 --- /dev/null +++ b/collections/ah_configuration/dispatch.md @@ -0,0 +1,111 @@ +--- +layout: default +title: dispatch +parent: infra.ah_configuration +--- + +# galaxy.galaxy.dispatch + +## Description + +An Ansible Role to run all roles for which variables are found on Ansible Automation Hub. + +## Before Using + +This collection is most useful for experienced AAP2 users who want to quickly configure a Automation Hub instance. + +If you are new to AAP2 and/or to the galaxy.galaxy collection, it is highly recommended that you ensure that you're familiar with both AAP2 and the collection, before using this role. + +## Variables + +Each role that is called also has its own variables. For information on those, please see the README documents for those roles. + +The key variable in this role is `ah_configuration_dispatcher_roles`. The default value is shown below: + +```yaml +ah_configuration_dispatcher_roles: + - {role: ansible_config, var: [ansible_config_list, automation_hub_list], tags: config} + - {role: collection, var: [ah_collections], tags: collections} + - {role: ee_image, var: [ah_ee_images], tags: images} + - {role: ee_registry, var: [ah_ee_registries], tags: registries} + - {role: ee_registry_index, var: [ah_ee_registries], tags: indices} + - {role: ee_registry_sync, var: [ah_ee_registries], tags: regsync} + - {role: ee_repository, var: [ah_ee_repositories], tags: repos} + - {role: ee_repository_sync, var: [ah_ee_repository_sync], tags: reposync} + - {role: namespace, var: [ah_namespaces], tags: namespaces} + - {role: group, var: [ah_groups], tags: groups} + - {role: publish, var: [ah_collections], tags: publish} + - {role: user, var: [ah_users], tags: users} +``` + +Each item within the variable has three elements: + +- `role` which is the name of the role within galaxy.galaxy +- `var` which is the variable or variables in that role. We use this to prevent the role being called if the variable is not set. +- `tags` the tags which are applied to the role so it is possible to apply tags to a playbook using the dispatcher with these tags. + +If the functionality of Automation Hub is extended in the future, and more variables are able to trigger a role, the new variable should be added into the `var` list for the role above. + +The `ah_configuration_async_dir` variable sets the directory to write the results file for async tasks. +The default value is set to `null` which uses the Ansible Default of `/root/.ansible_async/`. + +### Authentication + +|Variable Name|Default Value|Required|Description|Example| +|`ah_host`|""|yes|URL to the Automation Hub or Galaxy Server. (alias: `ah_hostname`)|127.0.0.1| +|`ah_username`|""|yes|Admin User on the Automation Hub or Galaxy Server.|| +|`ah_password`|""|yes|Automation Hub Admin User's password on the Automation Hub Server. This should be stored in an Ansible Vault at vars/tower-secrets.yml or elsewhere and called from a parent playbook.|| +|`ah_token`|""|yes|Tower Admin User's token on the Automation Hub Server. This should be stored in an Ansible Vault at or elsewhere and called from a parent playbook.|| +|`ah_validate_certs`|`true`|no|Whether or not to validate the Ansible Automation Hub Server's SSL certificate.|| +|`ah_path_prefix`|""|no|API path used to access the api. Either galaxy, automation-hub, or custom|| + +### Secure Logging Variables + +The role defaults to False as normally most projects task does not include sensitive information. +Each role the dispatch role calls has a separate variable which can be turned on to enforce secure logging for that role but defaults to the value of ah_configuration_secure_logging if it is not explicitly called. This allows for secure logging to be toggled for the entire suite of configuration roles with a single variable, or for the user to selectively use it. If neither value is set then each role has a default value of true or false as determined by best practices for each role. + +|Variable Name|Default Value|Required|Description| +|`ah_configuration_ee_registry_secure_logging`|`False`|no|Whether or not to include the sensitive Registry role tasks in the log. Set this value to `True` if you will be providing your sensitive values from elsewhere.| +|`ah_configuration_secure_logging`|""|no|This variable enables secure logging as well, but is shared across multiple roles, see above.| + +### Asynchronous Retry Variables + +The following Variables set asynchronous retries for the role. +If neither of the retries or delay or retries are set, they will default to their respective defaults. +This allows for all items to be created, then checked that the task finishes successfully. +This also speeds up the overall role. Each individual role has its own variable which can allow the individual setting of values. See each role for more the variable names. + +|Variable Name|Default Value|Required|Description| +|`ah_configuration_async_retries`|30|no|This variable sets the number of retries to attempt for the role globally.| +|`ah_configuration_async_delay`|1|no|This sets the delay between retries for the role globally.| + +## Playbook Examples + +### Standard Role Usage + +```yaml +- name: Playbook to configure Ansible Automation Hub post installation + hosts: localhost + connection: local + # Define following vars here, or in ah_configs/controller_auth.yml + # ah_hostname: ansible-ah-web-svc-test-project.example.com + # ah_username: admin + # ah_password: changeme + pre_tasks: + - name: Include vars from ah_configs directory + ansible.builtin.include_vars: + dir: ./yaml + ignore_files: [ah_config.yml.template] + extensions: ["yml"] + roles: + - galaxy.galaxy.dispatch +``` + +## License + +[GPLv3+](https://github.com/ansible/galaxy_collection#licensing) + +## Author + +[Alan Wong](https://github.com/alawong) +[Tom Page](https://github.com/Tompage1994) diff --git a/collections/ah_configuration/ee_image.md b/collections/ah_configuration/ee_image.md new file mode 100644 index 0000000..e3fe059 --- /dev/null +++ b/collections/ah_configuration/ee_image.md @@ -0,0 +1,106 @@ +--- +layout: default +title: ee_image +parent: infra.ah_configuration +--- + +# galaxy.galaxy.ee_image + +## Description + +An Ansible Role to create execution environment images in Automation Hub. + +## Variables + +|Variable Name|Default Value|Required|Description|Example| +|`ah_host`|""|yes|URL to the Automation Hub or Galaxy Server. (alias: `ah_hostname`)|127.0.0.1| +|`ah_username`|""|yes|Admin User on the Automation Hub or Galaxy Server.|| +|`ah_password`|""|yes|Automation Hub Admin User's password on the Automation Hub Server. This should be stored in an Ansible Vault at vars/tower-secrets.yml or elsewhere and called from a parent playbook.|| +|`ah_validate_certs`|`true`|no|Whether or not to validate the Ansible Automation Hub Server's SSL certificate.|| +|`ah_request_timeout`|`10`|no|Specify the timeout Ansible should use in requests to the Galaxy or Automation Hub host.|| +|`ah_path_prefix`|""|no|API path used to access the api. Either galaxy, automation-hub, or custom|| +|`ah_configuration_async_dir`|`null`|no|Sets the directory to write the results file for async tasks. The default value is set to `null` which uses the Ansible Default of `/root/.ansible_async/`.|| +|`ah_ee_images`|`see below`|yes|Data structure describing your execution environment images, described below.|| + +### Secure Logging Variables + +The following Variables compliment each other. +If Both variables are not set, secure logging defaults to false. +The role defaults to False as normally the add ee_image task does not include sensitive information. +ah_configuration_ee_image_secure_logging defaults to the value of ah_configuration_secure_logging if it is not explicitly called. This allows for secure logging to be toggled for the entire suite of automation hub configuration roles with a single variable, or for the user to selectively use it. + +|Variable Name|Default Value|Required|Description| +|`ah_configuration_ee_image_secure_logging`|`False`|no|Whether or not to include the sensitive Namespace role tasks in the log. Set this value to `True` if you will be providing your sensitive values from elsewhere.| +|`ah_configuration_secure_logging`|`False`|no|This variable enables secure logging as well, but is shared across multiple roles, see above.| + +### Asynchronous Retry Variables + +The following Variables set asynchronous retries for the role. +If neither of the retries or delay or retries are set, they will default to their respective defaults. +This allows for all items to be created, then checked that the task finishes successfully. +This also speeds up the overall role. + +|Variable Name|Default Value|Required|Description| +|`ah_configuration_async_timeout`|1000|no|This variable sets the async timeout for the role globally.| +|`ah_configuration_ee_image_async_timeout`|`ah_configuration_async_timeout`|no|This variable sets the async timeout for the role.| +|`ah_configuration_async_retries`|50|no|This variable sets the number of retries to attempt for the role globally.| +|`ah_configuration_ee_image_async_retries`|`ah_configuration_async_retries`|no|This variable sets the number of retries to attempt for the role.| +|`ah_configuration_async_delay`|1|no|This sets the delay between retries for the role globally.| +|`ah_configuration_ee_image_async_delay`|`ah_configuration_async_delay`|no|This sets the delay between retries for the role.| + +## Data Structure + +### EE Image Variables + +|Variable Name|Default Value|Required|Type|Description| +|`name`|""|yes|str|Execution environment image name. Must be lower case containing only alphanumeric characters and underscores.| +|`append`|`true`|no|bool|Whether to append or replace the tags specified to the image.| +|`tags`|""|no|str|List of the image tags to update.| +|`state`|`present`|no|str|Desired state of the ee_image. (Possible values of `present` or `absent`)| + +### Standard Project Data Structure + +#### Yaml Example + +```yaml +ah_ee_images: + - name: ansible-automation-platform-20-early-access/ee-supported-rhel8:2.0.0-15 + state: present + append: false + tags: + - v2 + - "2.0" + - prod1 +``` + +## Playbook Examples + +### Standard Role Usage + +```yaml +- name: Add ee_image to Automation Hub + hosts: localhost + connection: local + gather_facts: false + vars: + ah_validate_certs: false + # Define following vars here, or in ah_configs/ah_auth.yml + # ah_host: ansible-ah-web-svc-test-project.example.com + pre_tasks: + - name: Include vars from ah_configs directory + ansible.builtin.include_vars: + dir: ./vars + extensions: ["yml"] + tags: + - always + roles: + - ../../ee_image +``` + +## License + +[GPLv3+](https://github.com/ansible/galaxy_collection#licensing) + +## Author + +[Tom Page](https://github.com/Tompage1994/) diff --git a/collections/ah_configuration/ee_namespace.md b/collections/ah_configuration/ee_namespace.md new file mode 100644 index 0000000..6329372 --- /dev/null +++ b/collections/ah_configuration/ee_namespace.md @@ -0,0 +1,105 @@ +--- +layout: default +title: ee_namespace +parent: infra.ah_configuration +--- + +# galaxy.galaxy.ee_namespace + +## Description + +An Ansible Role to create Namespaces in Automation Hub. +This was depreciated with AAP 2.4 and Galaxy NG 4.6.3+, and removed from the API so it is no longer functional. Please use the ee_repository to achieve the same functionality. + +## Variables + +|Variable Name|Default Value|Required|Description|Example| +|`ah_host`|""|yes|URL to the Automation Hub or Galaxy Server. (alias: `ah_hostname`)|127.0.0.1| +|`ah_username`|""|yes|Admin User on the Automation Hub or Galaxy Server.|| +|`ah_password`|""|yes|Automation Hub Admin User's password on the Automation Hub Server. This should be stored in an Ansible Vault at vars/tower-secrets.yml or elsewhere and called from a parent playbook.|| +|`ah_validate_certs`|`true`|no|Whether or not to validate the Ansible Automation Hub Server's SSL certificate.|| +|`ah_request_timeout`|`10`|no|Specify the timeout Ansible should use in requests to the Galaxy or Automation Hub host.|| +|`ah_path_prefix`|""|no|API path used to access the api. Either galaxy, automation-hub, or custom|| +|`ah_configuration_async_dir`|`null`|no|Sets the directory to write the results file for async tasks. The default value is set to `null` which uses the Ansible Default of `/root/.ansible_async/`.|| +|`ah_ee_namespaces`|`see below`|yes|Data structure describing your ee_namespaces, described below.|| + +### Secure Logging Variables + +The following Variables compliment each other. +If Both variables are not set, secure logging defaults to false. +The role defaults to False as normally the add ee_namespace task does not include sensitive information. +ah_configuration_ee_namespace_secure_logging defaults to the value of ah_configuration_secure_logging if it is not explicitly called. This allows for secure logging to be toggled for the entire suite of automation hub configuration roles with a single variable, or for the user to selectively use it. + +|Variable Name|Default Value|Required|Description| +|`ah_configuration_ee_namespace_secure_logging`|`False`|no|Whether or not to include the sensitive Namespace role tasks in the log. Set this value to `True` if you will be providing your sensitive values from elsewhere.| +|`ah_configuration_secure_logging`|`False`|no|This variable enables secure logging as well, but is shared across multiple roles, see above.| + +### Asynchronous Retry Variables + +The following Variables set asynchronous retries for the role. +If neither of the retries or delay or retries are set, they will default to their respective defaults. +This allows for all items to be created, then checked that the task finishes successfully. +This also speeds up the overall role. + +|Variable Name|Default Value|Required|Description| +|`ah_configuration_async_timeout`|1000|no|This variable sets the async timeout for the role globally.| +|`ah_configuration_ee_namespace_async_timeout`|`ah_configuration_async_timeout`|no|This variable sets the async timeout for the role.| +|`ah_configuration_async_retries`|50|no|This variable sets the number of retries to attempt for the role globally.| +|`ah_configuration_ee_namespace_async_retries`|`ah_configuration_async_retries`|no|This variable sets the number of retries to attempt for the role.| +|`ah_configuration_async_delay`|1|no|This sets the delay between retries for the role globally.| +|`ah_configuration_ee_namespace_async_delay`|`ah_configuration_async_delay`|no|This sets the delay between retries for the role.| + +## Data Structure + +### EE Namespace Variables + +|Variable Name|Default Value|Required|Type|Description| +|`name`|""|yes|str|Namespace name. Must be lower case containing only alphanumeric characters and underscores.| +|`new_name`|""|yes|str|Setting this option will change the existing name (looked up via the name field.)| +|`append`|`true`|no|bool|Whether to append or replace the groups specified for the ee_namespace.| +|`groups`|[]|yes|list|A list of names for groups that control the Namespace.| +|`state`|`present`|no|str|Desired state of the ee_namespace.| + +### Standard Project Data Structure + +#### Yaml Example + +```yaml +ah_ee_namespaces: + - name: abc15 + append: true + groups: + - system:partner-engineers +``` + +## Playbook Examples + +### Standard Role Usage + +```yaml +- name: Add ee_namespace to Automation Hub + hosts: localhost + connection: local + gather_facts: false + vars: + ah_validate_certs: false + # Define following vars here, or in ah_configs/ah_auth.yml + # ah_host: ansible-ah-web-svc-test-project.example.com + pre_tasks: + - name: Include vars from ah_configs directory + ansible.builtin.include_vars: + dir: ./vars + extensions: ["yml"] + tags: + - always + roles: + - ../../ee_namespace +``` + +## License + +[GPLv3+](https://github.com/ansible/galaxy_collection#licensing) + +## Author + +[Tom Page](https://github.com/Tompage1994/) diff --git a/collections/ah_configuration/ee_registry.md b/collections/ah_configuration/ee_registry.md new file mode 100644 index 0000000..125b08b --- /dev/null +++ b/collections/ah_configuration/ee_registry.md @@ -0,0 +1,109 @@ +--- +layout: default +title: ee_registry +parent: infra.ah_configuration +--- + +# galaxy.galaxy.ee_registry + +## Description + +An Ansible Role to create EE Registries in Automation Hub. + +## Variables + +|Variable Name|Default Value|Required|Description|Example| +|`ah_host`|""|yes|URL to the Automation Hub or Galaxy Server. (alias: `ah_hostname`)|127.0.0.1| +|`ah_username`|""|yes|Admin User on the Automation Hub or Galaxy Server.|| +|`ah_password`|""|yes|Automation Hub Admin User's password on the Automation Hub Server. This should be stored in an Ansible Vault at vars/tower-secrets.yml or elsewhere and called from a parent playbook.|| +|`ah_validate_certs`|`true`|no|Whether or not to validate the Ansible Automation Hub Server's SSL certificate.|| +|`ah_request_timeout`|`10`|no|Specify the timeout Ansible should use in requests to the Galaxy or Automation Hub host.|| +|`ah_path_prefix`|""|no|API path used to access the api. Either galaxy, automation-hub, or custom|| +|`ah_configuration_async_dir`|`null`|no|Sets the directory to write the results file for async tasks. The default value is set to `null` which uses the Ansible Default of `/root/.ansible_async/`.|| +|`proxy_url`|""|no|str|The URL for the proxy. Defaults to global `proxy_url` variable.| +|`proxy_username`|""|no|str|The username for the proxy authentication. Defaults to global `proxy_username` variable.| +|`proxy_password`|""|no|str|The password for the proxy authentication. Defaults to global `proxy_password` variable.| +|`ah_ee_registries`|`see below`|yes|Data structure describing your ee_registries, described below.|| + +### Secure Logging Variables + +The following Variables compliment each other. +If Both variables are not set, secure logging defaults to false. +The role defaults to False as normally the add ee_registry task does not include sensitive information. +ah_configuration_ee_registry_secure_logging defaults to the value of ah_configuration_secure_logging if it is not explicitly called. This allows for secure logging to be toggled for the entire suite of automation hub configuration roles with a single variable, or for the user to selectively use it. + +|Variable Name|Default Value|Required|Description| +|`ah_configuration_ee_registry_secure_logging`|`False`|no|Whether or not to include the sensitive Registry role tasks in the log. Set this value to `True` if you will be providing your sensitive values from elsewhere.| +|`ah_configuration_secure_logging`|`False`|no|This variable enables secure logging as well, but is shared across multiple roles, see above.| + +### Asynchronous Retry Variables + +The following Variables set asynchronous retries for the role. +If neither of the retries or delay or retries are set, they will default to their respective defaults. +This allows for all items to be created, then checked that the task finishes successfully. +This also speeds up the overall role. + +|Variable Name|Default Value|Required|Description| +|`ah_configuration_async_timeout`|1000|no|This variable sets the async timeout for the role globally.| +|`ah_configuration_ee_registry_async_timeout`|`ah_configuration_async_timeout`|no|This variable sets the async timeout for the role.| +|`ah_configuration_async_retries`|50|no|This variable sets the number of retries to attempt for the role globally.| +|`ah_configuration_ee_registry_async_retries`|`ah_configuration_async_retries`|no|This variable sets the number of retries to attempt for the role.| +|`ah_configuration_async_delay`|1|no|This sets the delay between retries for the role globally.| +|`ah_configuration_ee_registry_async_delay`|`ah_configuration_async_delay`|no|This sets the delay between retries for the role.| + +## Data Structure + +### EE Registry Variables + +|Variable Name|Default Value|Required|Type|Description| +|`name`|""|yes|str|Registry name. Must be lower case containing only alphanumeric characters and underscores.| +|`new_name`|""|no|str|Setting this option will change the existing name (looked up via the name field.| +|`url`|""|yes|str|The URL for the registry| +|`username`|""|no|str|The username for authentication to the registry| +|`password`|""|no|str|The password for authentication to the registry| +|`tls_validation`|""|no|str|Whether to use TLS when connecting to the registry| +|`download_concurrency`|""|no|str|Number of concurrent collections to download| +|`rate_limit`|""|no|str|Limits total download rate in requests per second.| +|`state`|`present`|no|str|Desired state of the ee_registry.| + +### Standard Project Data Structure + +#### Yaml Example + +```yaml +ah_ee_registries: + - name: myreg + url: https://quay.io/my/registry +``` + +## Playbook Examples + +### Standard Role Usage + +```yaml +- name: Add ee_registry to Automation Hub + hosts: localhost + connection: local + gather_facts: false + vars: + ah_validate_certs: false + # Define following vars here, or in ah_configs/ah_auth.yml + # ah_host: ansible-ah-web-svc-test-project.example.com + pre_tasks: + - name: Include vars from ah_configs directory + ansible.builtin.include_vars: + dir: ./vars + extensions: ["yml"] + tags: + - always + roles: + - ../../ee_registry +``` + +## License + +[GPLv3+](https://github.com/ansible/galaxy_collection#licensing) + +## Author + +[Tom Page](https://github.com/Tompage1994/) diff --git a/collections/ah_configuration/ee_registry_index.md b/collections/ah_configuration/ee_registry_index.md new file mode 100644 index 0000000..0ce3d8a --- /dev/null +++ b/collections/ah_configuration/ee_registry_index.md @@ -0,0 +1,105 @@ +--- +layout: default +title: ee_registry_index +parent: infra.ah_configuration +--- + +# galaxy.galaxy.ee_registry_index + +## Description + +An Ansible Role to index EE Registries in Automation Hub. + +## Variables + +|Variable Name|Default Value|Required|Description|Example| +|`ah_host`|""|yes|URL to the Automation Hub or Galaxy Server. (alias: `ah_hostname`)|127.0.0.1| +|`ah_username`|""|yes|Admin User on the Automation Hub or Galaxy Server.|| +|`ah_password`|""|yes|Automation Hub Admin User's password on the Automation Hub Server. This should be stored in an Ansible Vault at vars/tower-secrets.yml or elsewhere and called from a parent playbook.|| +|`ah_validate_certs`|`true`|no|Whether or not to validate the Ansible Automation Hub Server's SSL certificate.|| +|`ah_request_timeout`|`10`|no|Specify the timeout Ansible should use in requests to the Galaxy or Automation Hub host.|| +|`ah_path_prefix`|""|no|API path used to access the api. Either galaxy, automation-hub, or custom|| +|`ah_configuration_async_dir`|`null`|no|Sets the directory to write the results file for async tasks. The default value is set to `null` which uses the Ansible Default of `/root/.ansible_async/`.|| +|`ah_ee_registries`|`see below`|yes|Data structure describing your ee_registries, described below. (Note this is the same as for the `ee_registries` role and the variable can be combined). Note that this role will only do anything if the `index` suboption of this variable is set to true.|| + +### Secure Logging Variables + +The following Variables compliment each other. +If Both variables are not set, secure logging defaults to false. +The role defaults to False as normally the add ee_registry task does not include sensitive information. +ah_configuration_ee_registry_secure_logging defaults to the value of ah_configuration_secure_logging if it is not explicitly called. This allows for secure logging to be toggled for the entire suite of automation hub configuration roles with a single variable, or for the user to selectively use it. + +|Variable Name|Default Value|Required|Description| +|`ah_configuration_ee_registry_secure_logging`|`False`|no|Whether or not to include the sensitive Registry role tasks in the log. Set this value to `True` if you will be providing your sensitive values from elsewhere.| +|`ah_configuration_secure_logging`|`False`|no|This variable enables secure logging as well, but is shared across multiple roles, see above.| + +### Asynchronous Retry Variables + +The following Variables set asynchronous retries for the role. +If neither of the retries or delay or retries are set, they will default to their respective defaults. +This allows for all items to be created, then checked that the task finishes successfully. +This also speeds up the overall role. + +|Variable Name|Default Value|Required|Description| +|`ah_configuration_async_timeout`|1000|no|This variable sets the async timeout for the role globally.| +|`ah_configuration_ee_registry_index_async_timeout`|`ah_configuration_async_timeout`|no|This variable sets the async timeout for the role.| +|`ah_configuration_async_retries`|50|no|This variable sets the number of retries to attempt for the role globally.| +|`ah_configuration_ee_registry_index_async_retries`|`ah_configuration_async_retries`|no|This variable sets the number of retries to attempt for the role.| +|`ah_configuration_async_delay`|1|no|This sets the delay between retries for the role globally.| +|`ah_configuration_ee_registry_index_async_delay`|`ah_configuration_async_delay`|no|This sets the delay between retries for the role.| + +## Data Structure + +### EE Registry Variables + +|Variable Name|Default Value|Required|Type|Description| +|`name`|""|yes|str|Registry name. Must be lower case containing only alphanumeric characters and underscores.| +|`index`|false|no|bool|Whether to index the ee_registry. Bu default it will not index unless this is set to true.| +|`wait`|true|no|str|Whether to wait for the indexing to complete| +|`interval`|`ah_configuration_ee_registry_index_async_delay`|no|str|The interval which the indexing task will be checked for completion| +|`timeout`|""|no|str|How long to wait for the indexing task to complete| + +### Standard Project Data Structure + +#### Yaml Example + +```yaml +ah_ee_registries: + - name: myreg + url: https://quay.io/my/registry + interval: 10 + wait: true + timeout: 300 +``` + +## Playbook Examples + +### Standard Role Usage + +```yaml +- name: Index ee_registry in Automation Hub + hosts: localhost + connection: local + gather_facts: false + vars: + ah_validate_certs: false + # Define following vars here, or in ah_configs/ah_auth.yml + # ah_host: ansible-ah-web-svc-test-project.example.com + pre_tasks: + - name: Include vars from ah_configs directory + ansible.builtin.include_vars: + dir: ./vars + extensions: ["yml"] + tags: + - always + roles: + - ee_registry_index +``` + +## License + +[GPLv3+](https://github.com/ansible/galaxy_collection#licensing) + +## Author + +[Tom Page](https://github.com/Tompage1994/) diff --git a/collections/ah_configuration/ee_registry_sync.md b/collections/ah_configuration/ee_registry_sync.md new file mode 100644 index 0000000..de764d0 --- /dev/null +++ b/collections/ah_configuration/ee_registry_sync.md @@ -0,0 +1,105 @@ +--- +layout: default +title: ee_registry_sync +parent: infra.ah_configuration +--- + +# galaxy.galaxy.ee_registry_sync + +## Description + +An Ansible Role to sync EE Registries in Automation Hub. + +## Variables + +|Variable Name|Default Value|Required|Description|Example| +|`ah_host`|""|yes|URL to the Automation Hub or Galaxy Server. (alias: `ah_hostname`)|127.0.0.1| +|`ah_username`|""|yes|Admin User on the Automation Hub or Galaxy Server.|| +|`ah_password`|""|yes|Automation Hub Admin User's password on the Automation Hub Server. This should be stored in an Ansible Vault at vars/tower-secrets.yml or elsewhere and called from a parent playbook.|| +|`ah_validate_certs`|`true`|no|Whether or not to validate the Ansible Automation Hub Server's SSL certificate.|| +|`ah_request_timeout`|`10`|no|Specify the timeout Ansible should use in requests to the Galaxy or Automation Hub host.|| +|`ah_path_prefix`|""|no|API path used to access the api. Either galaxy, automation-hub, or custom|| +|`ah_configuration_async_dir`|`null`|no|Sets the directory to write the results file for async tasks. The default value is set to `null` which uses the Ansible Default of `/root/.ansible_async/`.|| +|`ah_ee_registries`|`see below`|yes|Data structure describing your ee_registries, described below. (Note this is the same as for the `ee_registries` role and the variable can be combined. Note that this role will only do anything if the `sync` suboption of this variable is set to true.|| + +### Secure Logging Variables + +The following Variables compliment each other. +If Both variables are not set, secure logging defaults to false. +The role defaults to False as normally the add ee_registry task does not include sensitive information. +ah_configuration_ee_registry_secure_logging defaults to the value of ah_configuration_secure_logging if it is not explicitly called. This allows for secure logging to be toggled for the entire suite of automation hub configuration roles with a single variable, or for the user to selectively use it. + +|Variable Name|Default Value|Required|Description| +|`ah_configuration_ee_registry_secure_logging`|`False`|no|Whether or not to include the sensitive Registry role tasks in the log. Set this value to `True` if you will be providing your sensitive values from elsewhere.| +|`ah_configuration_secure_logging`|`False`|no|This variable enables secure logging as well, but is shared across multiple roles, see above.| + +### Asynchronous Retry Variables + +The following Variables set asynchronous retries for the role. +If neither of the retries or delay or retries are set, they will default to their respective defaults. +This allows for all items to be created, then checked that the task finishes successfully. +This also speeds up the overall role. + +|Variable Name|Default Value|Required|Description| +|`ah_configuration_async_timeout`|1000|no|This variable sets the async timeout for the role globally.| +|`ah_configuration_ee_repository_sync_async_timeout`|`ah_configuration_async_timeout`|no|This variable sets the async timeout for the role.| +|`ah_configuration_async_retries`|50|no|This variable sets the number of retries to attempt for the role globally.| +|`ah_configuration_ee_registry_sync_async_retries`|`ah_configuration_async_retries`|no|This variable sets the number of retries to attempt for the role.| +|`ah_configuration_async_delay`|1|no|This sets the delay between retries for the role globally.| +|`ah_configuration_ee_registry_sync_async_delay`|`ah_configuration_async_delay`|no|This sets the delay between retries for the role.| + +## Data Structure + +### Registry Variables + +|Variable Name|Default Value|Required|Type|Description| +|`name`|""|yes|str|Registry name. Must be lower case containing only alphanumeric characters and underscores.| +|`sync`|false|no|bool|Whether to sync the ee_registry. By default it will not sync unless this is set to true.| +|`wait`|true|no|str|Whether to wait for the sync to complete| +|`interval`|`ah_configuration_ee_registry_sync_async_delay`|no|str|The interval which the sync task will be checked for completion| +|`timeout`|""|no|str|How long to wait for the sync task to complete| + +### Standard Project Data Structure + +#### Yaml Example + +```yaml +ah_ee_registries: + - name: myreg + url: https://quay.io/my/registry + interval: 10 + wait: true + timeout: 300 +``` + +## Playbook Examples + +### Standard Role Usage + +```yaml +- name: Sync ee_registry in Automation Hub + hosts: localhost + connection: local + gather_facts: false + vars: + ah_validate_certs: false + # Define following vars here, or in ah_configs/ah_auth.yml + # ah_host: ansible-ah-web-svc-test-project.example.com + pre_tasks: + - name: Include vars from ah_configs directory + ansible.builtin.include_vars: + dir: ./vars + extensions: ["yml"] + tags: + - always + roles: + - ee_registry_sync +``` + +## License + +[GPLv3+](https://github.com/ansible/galaxy_collection#licensing) + +## Author + +[Tom Page](https://github.com/Tompage1994/) diff --git a/collections/ah_configuration/ee_repository.md b/collections/ah_configuration/ee_repository.md new file mode 100644 index 0000000..9cb9cca --- /dev/null +++ b/collections/ah_configuration/ee_repository.md @@ -0,0 +1,107 @@ +--- +layout: default +title: ee_repository +parent: infra.ah_configuration +--- + +# galaxy.galaxy.ee_repository + +## Description + +An Ansible Role to create Repositories in Automation Hub. + +## Variables + +|Variable Name|Default Value|Required|Description|Example| +|`ah_host`|""|yes|URL to the Automation Hub or Galaxy Server. (alias: `ah_hostname`)|127.0.0.1| +|`ah_username`|""|yes|Admin User on the Automation Hub or Galaxy Server.|| +|`ah_password`|""|yes|Automation Hub Admin User's password on the Automation Hub Server. This should be stored in an Ansible Vault at vars/tower-secrets.yml or elsewhere and called from a parent playbook.|| +|`ah_validate_certs`|`true`|no|Whether or not to validate the Ansible Automation Hub Server's SSL certificate.|| +|`ah_request_timeout`|`10`|no|Specify the timeout Ansible should use in requests to the Galaxy or Automation Hub host.|| +|`ah_path_prefix`|""|no|API path used to access the api. Either galaxy, automation-hub, or custom|| +|`ah_configuration_async_dir`|`null`|no|Sets the directory to write the results file for async tasks. The default value is set to `null` which uses the Ansible Default of `/root/.ansible_async/`.|| +|`ah_ee_repositories`|`see below`|yes|Data structure describing your ee_repositories, described below.|| + +### Secure Logging Variables + +The following Variables compliment each other. +If Both variables are not set, secure logging defaults to false. +The role defaults to False as normally the add ee_repository task does not include sensitive information. +ah_configuration_ee_repository_secure_logging defaults to the value of ah_configuration_secure_logging if it is not explicitly called. This allows for secure logging to be toggled for the entire suite of automation hub configuration roles with a single variable, or for the user to selectively use it. + +|Variable Name|Default Value|Required|Description| +|`ah_configuration_ee_repository_secure_logging`|`False`|no|Whether or not to include the sensitive Namespace role tasks in the log. Set this value to `True` if you will be providing your sensitive values from elsewhere.| +|`ah_configuration_secure_logging`|`False`|no|This variable enables secure logging as well, but is shared across multiple roles, see above.| + +### Asynchronous Retry Variables + +The following Variables set asynchronous retries for the role. +If neither of the retries or delay or retries are set, they will default to their respective defaults. +This allows for all items to be created, then checked that the task finishes successfully. +This also speeds up the overall role. + +|Variable Name|Default Value|Required|Description| +|`ah_configuration_async_timeout`|1000|no|This variable sets the async timeout for the role globally.| +|`ah_configuration_ee_repository_async_timeout`|`ah_configuration_async_timeout`|no|This variable sets the async timeout for the role.| +|`ah_configuration_async_retries`|50|no|This variable sets the number of retries to attempt for the role globally.| +|`ah_configuration_ee_repository_async_retries`|`ah_configuration_async_retries`|no|This variable sets the number of retries to attempt for the role.| +|`ah_configuration_async_delay`|1|no|This sets the delay between retries for the role globally.| +|`ah_configuration_ee_repository_async_delay`|`ah_configuration_async_delay`|no|This sets the delay between retries for the role.| + +## Data Structure + +### Repository Variables + +|Variable Name|Default Value|Required|Type|Description| +|`name`|""|yes|str|Repository name. Must be lower case containing only alphanumeric characters and underscores.| +|`description`|""|yes|str|Description to use for the Repository.| +|`readme`|""|no|str|The readme for the ee repository. (mutex with readme_file)| +|`readme_file`|""|no|str|The file location for the readme for the ee repository. (mutex with readme)| +|`state`|`present`|no|str|Desired state of the ee_repository.| +|`registry`|""|no|str|The remote registry that the repository belongs in.| +|`upstream_name`|""|no|str|The name of the image upstream.| +|`include_tags`|""|no|str|The tags to pull in.| +|`exclude_tags`|""|no|str|The tags to avoid pulling in.| + +### Standard Project Data Structure + +#### Yaml Example + +```yaml +ah_ee_repositories: + - name: abc15 + description: string + readme: "# My ee repo" +``` + +## Playbook Examples + +### Standard Role Usage + +```yaml +- name: Add ee_repository to Automation Hub + hosts: localhost + connection: local + gather_facts: false + vars: + ah_validate_certs: false + # Define following vars here, or in ah_configs/ah_auth.yml + # ah_host: ansible-ah-web-svc-test-project.example.com + pre_tasks: + - name: Include vars from ah_configs directory + ansible.builtin.include_vars: + dir: ./vars + extensions: ["yml"] + tags: + - always + roles: + - ../../ee_repository +``` + +## License + +[GPLv3+](https://github.com/ansible/galaxy_collection#licensing) + +## Author + +[Tom Page](https://github.com/Tompage1994/) diff --git a/collections/ah_configuration/ee_repository_sync.md b/collections/ah_configuration/ee_repository_sync.md new file mode 100644 index 0000000..50d44eb --- /dev/null +++ b/collections/ah_configuration/ee_repository_sync.md @@ -0,0 +1,105 @@ +--- +layout: default +title: ee_repository_sync +parent: infra.ah_configuration +--- + +# galaxy.galaxy.ee_repository_sync + +## Description + +An Ansible Role to sync EE Repositories in Automation Hub. + +## Variables + +|Variable Name|Default Value|Required|Description|Example| +|`ah_host`|""|yes|URL to the Automation Hub or Galaxy Server. (alias: `ah_hostname`)|127.0.0.1| +|`ah_username`|""|yes|Admin User on the Automation Hub or Galaxy Server.|| +|`ah_password`|""|yes|Automation Hub Admin User's password on the Automation Hub Server. This should be stored in an Ansible Vault at vars/tower-secrets.yml or elsewhere and called from a parent playbook.|| +|`ah_validate_certs`|`true`|no|Whether or not to validate the Ansible Automation Hub Server's SSL certificate.|| +|`ah_request_timeout`|`10`|no|Specify the timeout Ansible should use in requests to the Galaxy or Automation Hub host.|| +|`ah_path_prefix`|""|no|API path used to access the api. Either galaxy, automation-hub, or custom|| +|`ah_configuration_async_dir`|`null`|no|Sets the directory to write the results file for async tasks. The default value is set to `null` which uses the Ansible Default of `/root/.ansible_async/`.|| +|`ah_ee_repositories`|`see below`|yes|Data structure describing your ee_repositories, described below. (Note this is the same as for the `ee_repository` role and the variable can be combined. Note that this role will only do anything if the `sync` suboption of this variable is set to true.|| + +### Secure Logging Variables + +The following Variables compliment each other. +If Both variables are not set, secure logging defaults to false. +The role defaults to False as normally the add ee_repository task does not include sensitive information. +ah_configuration_ee_repository_secure_logging defaults to the value of ah_configuration_secure_logging if it is not explicitly called. This allows for secure logging to be toggled for the entire suite of automation hub configuration roles with a single variable, or for the user to selectively use it. + +|Variable Name|Default Value|Required|Description| +|`ah_configuration_ee_repository_secure_logging`|`False`|no|Whether or not to include the sensitive Repository role tasks in the log. Set this value to `True` if you will be providing your sensitive values from elsewhere.| +|`ah_configuration_secure_logging`|`False`|no|This variable enables secure logging as well, but is shared across multiple roles, see above.| + +### Asynchronous Retry Variables + +The following Variables set asynchronous retries for the role. +If neither of the retries or delay or retries are set, they will default to their respective defaults. +This allows for all items to be created, then checked that the task finishes successfully. +This also speeds up the overall role. + +|Variable Name|Default Value|Required|Description| +|`ah_configuration_async_timeout`|1000|no|This variable sets the async timeout for the role globally.| +|`ah_configuration_ee_repository_sync_async_timeout`|`ah_configuration_async_timeout`|no|This variable sets the async timeout for the role.| +|`ah_configuration_async_retries`|50|no|This variable sets the number of retries to attempt for the role globally.| +|`ah_configuration_ee_repository_sync_async_retries`|`ah_configuration_async_retries`|no|This variable sets the number of retries to attempt for the role.| +|`ah_configuration_async_delay`|1|no|This sets the delay between retries for the role globally.| +|`ah_configuration_ee_repository_sync_async_delay`|`ah_configuration_async_delay`|no|This sets the delay between retries for the role.| + +## Data Structure + +### Repository Variables + +|Variable Name|Default Value|Required|Type|Description| +|`name`|""|yes|str|Repository name. Must be lower case containing only alphanumeric characters and underscores.| +|`sync`|false|no|bool|Whether to sync the ee_registry. By default it will not sync unless this is set to true.| +|`wait`|true|no|str|Whether to wait for the sync to complete| +|`interval`|`ah_configuration_ee_repository_sync_async_delay`|no|str|The interval which the sync task will be checked for completion| +|`timeout`|""|no|str|How long to wait for the sync task to complete| + +### Standard Project Data Structure + +#### Yaml Example + +```yaml +ah_ee_repositories: + - name: abc15 + description: string + readme: "# My EE repository" + wait: true + interval: 10 +``` + +## Playbook Examples + +### Standard Role Usage + +```yaml +- name: Sync ee_repository in Automation Hub + hosts: localhost + connection: local + gather_facts: false + vars: + ah_validate_certs: false + # Define following vars here, or in ah_configs/ah_auth.yml + # ah_host: ansible-ah-web-svc-test-project.example.com + pre_tasks: + - name: Include vars from ah_configs directory + ansible.builtin.include_vars: + dir: ./vars + extensions: ["yml"] + tags: + - always + roles: + - ee_repository_sync +``` + +## License + +[GPLv3+](https://github.com/ansible/galaxy_collection#licensing) + +## Author + +[Tom Page](https://github.com/Tompage1994/) diff --git a/collections/ah_configuration/group.md b/collections/ah_configuration/group.md new file mode 100644 index 0000000..3cff77d --- /dev/null +++ b/collections/ah_configuration/group.md @@ -0,0 +1,113 @@ +--- +layout: default +title: group +parent: infra.ah_configuration +--- + +# galaxy.galaxy.group + +## Description + +An Ansible Role to create groups in Automation Hub. + +## Variables + +|Variable Name|Default Value|Required|Description|Example| +|`ah_host`|""|yes|URL to the Automation Hub or Galaxy Server. (alias: `ah_hostname`)|127.0.0.1| +|`ah_username`|""|yes|Admin User on the Automation Hub or Galaxy Server.|| +|`ah_password`|""|yes|Automation Hub Admin User's password on the Automation Hub Server. This should be stored in an Ansible Vault at vars/tower-secrets.yml or elsewhere and called from a parent playbook.|| +|`ah_validate_certs`|`true`|no|Whether or not to validate the Ansible Automation Hub Server's SSL certificate.|| +|`ah_request_timeout`|`10`|no|Specify the timeout Ansible should use in requests to the Galaxy or Automation Hub host.|| +|`ah_path_prefix`|""|no|API path used to access the api. Either galaxy, automation-hub, or custom|| +|`ah_configuration_async_dir`|`null`|no|Sets the directory to write the results file for async tasks. The default value is set to `null` which uses the Ansible Default of `/root/.ansible_async/`.|| +|`ah_groups`|`see below`|yes|Data structure describing your groups, described below.|| + +### Secure Logging Variables + +The following Variables compliment each other. +If Both variables are not set, secure logging defaults to false. +The role defaults to False as normally the add group task does not include sensitive information. +ah_configuration_group_secure_logging defaults to the value of ah_configuration_secure_logging if it is not explicitly called. This allows for secure logging to be toggled for the entire suite of automation hub configuration roles with a single variable, or for the user to selectively use it. + +|Variable Name|Default Value|Required|Description| +|`ah_configuration_group_secure_logging`|`False`|no|Whether or not to include the sensitive Namespace role tasks in the log. Set this value to `True` if you will be providing your sensitive values from elsewhere.| +|`ah_configuration_secure_logging`|`False`|no|This variable enables secure logging as well, but is shared across multiple roles, see above.| + +### Asynchronous Retry Variables + +The following Variables set asynchronous retries for the role. +If neither of the retries or delay or retries are set, they will default to their respective defaults. +This allows for all items to be created, then checked that the task finishes successfully. +This also speeds up the overall role. + +|Variable Name|Default Value|Required|Description| +|`ah_configuration_async_retries`|50|no|This variable sets the number of retries to attempt for the role globally.| +|`ah_configuration_group_async_retries`|`ah_configuration_async_retries`|no|This variable sets the number of retries to attempt for the role.| +|`ah_configuration_async_delay`|1|no|This sets the delay between retries for the role globally.| +|`ah_configuration_group_async_delay`|`ah_configuration_async_delay`|no|This sets the delay between retries for the role.| + +## Data Structure + +### Group Variables + +|Variable Name|Default Value|Required|Type|Description| +|`name`|""|yes|str|Group Name. Must be lower case containing only alphanumeric characters and underscores.| +|`perms`|""|yes|str|The list of permissions to add to or remove from the given group. See below for options.| +|`state`|`present`|no|str|Desired state of the group.| + +#### perms + +The module accepts the following roles: + +- For user management, `add_user`, `change_user`, `delete_user`, and `view_user`. +- For group management, `add_group`, `change_group`, `delete_group`, and `view_group`. +- For collection namespace management, `add_namespace`, `change_namespace`, `upload_to_namespace`, and `delete_namespace`. +- For collection content management, `modify_ansible_repo_content`, and `delete_collection`. +- For remote repository configuration, `change_collectionremote` and `view_collectionremote`. +- For container image management, only with private automation hub v4.3.2 + or later, `change_containernamespace_perms`, `change_container`, + `change_image_tag`, `create_container`, `push_container`, and `delete_containerrepository`. +- For task management, `change_task`, `view_task`, and `delete_task`. +- You can also grant or revoke all permissions with `*` or `all`. + +### Standard Project Data Structure + +#### Yaml Example + +```yaml +ah_groups: + - name: group1 + state: present +``` + +## Playbook Examples + +### Standard Role Usage + +```yaml +- name: Add group to Automation Hub + hosts: localhost + connection: local + gather_facts: false + vars: + ah_validate_certs: false + # Define following vars here, or in ah_configs/ah_auth.yml + # ah_host: ansible-ah-web-svc-test-project.example.com + pre_tasks: + - name: Include vars from ah_configs directory + ansible.builtin.include_vars: + dir: ./vars + extensions: ["yml"] + tags: + - always + roles: + - ../../group +``` + +## License + +[GPLv3+](https://github.com/ansible/galaxy_collection#licensing) + +## Author + +[Tom Page](https://github.com/Tompage1994/) diff --git a/collections/ah_configuration/group_roles.md b/collections/ah_configuration/group_roles.md new file mode 100644 index 0000000..81fa72c --- /dev/null +++ b/collections/ah_configuration/group_roles.md @@ -0,0 +1,154 @@ +--- +layout: default +title: group_roles +parent: infra.ah_configuration +--- + +# group_roles + +## Description + +An Ansible Role to add roles to groups in Automation Hub. + +## Variables + +|Variable Name|Default Value|Required|Description|Example| +|`ah_host`|""|yes|URL to the Automation Hub or Galaxy Server. (alias: `ah_hostname`)|127.0.0.1| +|`ah_username`|""|yes|Admin User on the Automation Hub or Galaxy Server.|| +|`ah_password`|""|yes|Automation Hub Admin User's password on the Automation Hub Server. This should be stored in an Ansible Vault at vars/tower-secrets.yml or elsewhere and called from a parent playbook.|| +|`ah_validate_certs`|`true`|no|Whether or not to validate the Ansible Automation Hub Server's SSL certificate.|| +|`ah_request_timeout`|`10`|no|Specify the timeout Ansible should use in requests to the Galaxy or Automation Hub host.|| +|`ah_path_prefix`|""|no|API path used to access the api. Either galaxy, automation-hub, or custom|| +|`ah_configuration_async_dir`|`null`|no|Sets the directory to write the results file for async tasks. The default value is set to `null` which uses the Ansible Default of `/root/.ansible_async/`.|| +|`ah_group_roles`|`see below`|yes|Data structure describing the roles which are applied to groups, described below.|| + +### Secure Logging Variables + +The following Variables compliment each other. +If Both variables are not set, secure logging defaults to false. +The role defaults to False as normally the add group task does not include sensitive information. +ah_configuration_group_secure_logging defaults to the value of ah_configuration_secure_logging if it is not explicitly called. This allows for secure logging to be toggled for the entire suite of automation hub configuration roles with a single variable, or for the user to selectively use it. + +|Variable Name|Default Value|Required|Description| +|`ah_configuration_group_secure_logging`|`False`|no|Whether or not to include the sensitive Namespace role tasks in the log. Set this value to `True` if you will be providing your sensitive values from elsewhere.| +|`ah_configuration_secure_logging`|`False`|no|This variable enables secure logging as well, but is shared across multiple roles, see above.| + +### Asynchronous Retry Variables + +The following Variables set asynchronous retries for the role. +If neither of the retries or delay or retries are set, they will default to their respective defaults. +This allows for all items to be created, then checked that the task finishes successfully. +This also speeds up the overall role. + +|Variable Name|Default Value|Required|Description| +|`ah_configuration_async_timeout`|1000|no|This variable sets the async timeout for the role globally.| +|`ah_configuration_group_roles_async_timeout`|`ah_configuration_async_timeout`|no|This variable sets the async timeout for the role.| +|`ah_configuration_async_retries`|50|no|This variable sets the number of retries to attempt for the role globally.| +|`ah_configuration_group_roles_async_retries`|`ah_configuration_async_retries`|no|This variable sets the number of retries to attempt for the role.| +|`ah_configuration_async_delay`|1|no|This sets the delay between retries for the role globally.| +|`ah_configuration_group_roles_async_delay`|`ah_configuration_async_delay`|no|This sets the delay between retries for the role.| + +## Data Structure + +### Group Variables + +|Variable Name|Default Value|Required|Type|Description| +|`groups`|""|yes|str| List of Group Names to apply the roles to. If the group does not exist, it will be created. Must be lower case containing only alphanumeric characters and underscores.| +|`role_list`|""|yes|str|The list of roles to add to or remove from the given group. See below for options.| +|`state`|`present`|no|str|Desired state of the group. Can be `present`, `enforced`, or `absent`. If absent, then the module deletes the given combination of roles for given groups. If present, then the module creates the group roles if it does not already exist. If enforced, then the module will remove any group role combinations not provided.| + +#### role_list + +The `role_list` variable is a combination of roles and targets that are applied to the groups listed in `groups`. +The structure look slike + +```yaml +- roles: + - container.containerdistribution_owner + targets: + execution_environments: + - ee-minimal-rhel8 +``` + +Roles can be those that were created using the `role` role, the `ah_role`, or the built in roles. + +If no targets are listed, the roles are applied globally to the groups. +Targets consist of the following. + +|Target|Description| +|`collection_namespaces`|List of collection namespaces to apply the roles to.| +|`collection_remotes`|List of collection remotes to apply the roles to.| +|`collection_repositories`|List of collection repositories to apply the roles to.| +|`execution_environments`|List of execution environments to apply the roles to.| +|`container_registery_remotes`|List of container registry remotes to apply the roles to.| + +#### Yaml Example + +```yaml +ah_group_roles: + - state: present + groups: + - santa + - group1 + role_list: + - roles: + - container.containerdistribution_owner + targets: + execution_environments: + - redhat_cop/config_as_code_ee + - roles: + - galaxy.container_remote + targets: + container_registery_remotes: + - quay + - roles: + - galaxy.user_admin + - galaxy.group_admin + - roles: + - galaxy.ansible_repository_owner + targets: + collection_repositories: + - validated + - roles: + - galaxy.collection_remote_owner + targets: + collection_remotes: + - community + - roles: + - galaxy.collection_namespace_owner + targets: + collection_namespaces: + - autohubtest2 +``` + +## Playbook Examples + +### Standard Role Usage + +```yaml +- name: Add group roles to Automation Hub + hosts: localhost + connection: local + gather_facts: false + vars: + ah_validate_certs: false + # Define following vars here, or in ah_configs/ah_auth.yml + # ah_host: ansible-ah-web-svc-test-project.example.com + pre_tasks: + - name: Include vars from ah_configs directory + ansible.builtin.include_vars: + dir: ./vars + extensions: ["yml"] + tags: + - always + roles: + - ../../group_roles +``` + +## License + +[GPLv3+](https://github.com/ansible/galaxy_collection#licensing) + +## Author + +[Tom Page](https://github.com/Tompage1994/) diff --git a/collections/ah_configuration/index.md b/collections/ah_configuration/index.md new file mode 100644 index 0000000..992e231 --- /dev/null +++ b/collections/ah_configuration/index.md @@ -0,0 +1,8 @@ +--- +layout: default +title: infra.ah_configuration +has_children: true +nav_order: 3 +--- + +# ah_configuration \ No newline at end of file diff --git a/collections/ah_configuration/namespace.md b/collections/ah_configuration/namespace.md new file mode 100644 index 0000000..a35717d --- /dev/null +++ b/collections/ah_configuration/namespace.md @@ -0,0 +1,127 @@ +--- +layout: default +title: namespace +parent: infra.ah_configuration +--- + +# galaxy.galaxy.namespace + +## Description + +An Ansible Role to create Namespaces in Automation Hub. + +## Variables + +|Variable Name|Default Value|Required|Description|Example| +|`ah_host`|""|yes|URL to the Automation Hub or Galaxy Server. (alias: `ah_hostname`)|127.0.0.1| +|`ah_username`|""|yes|Admin User on the Automation Hub or Galaxy Server.|| +|`ah_password`|""|yes|Automation Hub Admin User's password on the Automation Hub Server. This should be stored in an Ansible Vault at vars/tower-secrets.yml or elsewhere and called from a parent playbook.|| +|`ah_token`|""|yes|Tower Admin User's token on the Automation Hub Server. This should be stored in an Ansible Vault at or elsewhere and called from a parent playbook.|| +|`ah_validate_certs`|`true`|no|Whether or not to validate the Ansible Automation Hub Server's SSL certificate.|| +|`ah_request_timeout`|`10`|no|Specify the timeout Ansible should use in requests to the Galaxy or Automation Hub host.|| +|`ah_path_prefix`|""|no|API path used to access the api. Either galaxy, automation-hub, or custom|| +|`ah_configuration_async_dir`|`null`|no|Sets the directory to write the results file for async tasks. The default value is set to `null` which uses the Ansible Default of `/root/.ansible_async/`.|| +|`ah_namespaces`|`see below`|yes|Data structure describing your namespaces, described below.|| + +### Secure Logging Variables + +The following Variables compliment each other. +If Both variables are not set, secure logging defaults to false. +The role defaults to False as normally the add namespace task does not include sensitive information. +ah_configuration_namespace_secure_logging defaults to the value of ah_configuration_secure_logging if it is not explicitly called. This allows for secure logging to be toggled for the entire suite of automation hub configuration roles with a single variable, or for the user to selectively use it. + +|Variable Name|Default Value|Required|Description| +|`ah_configuration_namespace_secure_logging`|`False`|no|Whether or not to include the sensitive Namespace role tasks in the log. Set this value to `True` if you will be providing your sensitive values from elsewhere.| +|`ah_configuration_secure_logging`|`False`|no|This variable enables secure logging as well, but is shared across multiple roles, see above.| + +### Asynchronous Retry Variables + +The following Variables set asynchronous retries for the role. +If neither of the retries or delay or retries are set, they will default to their respective defaults. +This allows for all items to be created, then checked that the task finishes successfully. +This also speeds up the overall role. + +|Variable Name|Default Value|Required|Description| +|`ah_configuration_async_timeout`|1000|no|This variable sets the async timeout for the role globally.| +|`ah_configuration_namespace_async_timeout`|`ah_configuration_async_timeout`|no|This variable sets the async timeout for the role.| +|`ah_configuration_async_retries`|50|no|This variable sets the number of retries to attempt for the role globally.| +|`ah_configuration_namespace_async_retries`|`ah_configuration_async_retries`|no|This variable sets the number of retries to attempt for the role.| +|`ah_configuration_async_delay`|1|no|This sets the delay between retries for the role globally.| +|`ah_configuration_namespace_async_delay`|`ah_configuration_async_delay`|no|This sets the delay between retries for the role.| + +## Data Structure + +### Namespace Variables + +|Variable Name|Default Value|Required|Type|Description| +|`name`|""|yes|str|Namespace name. Must be lower case containing only alphanumeric characters and underscores.| +|`new_name`|""|yes|str|Setting this option will change the existing name (looked up via the name field.| +|`description`|""|yes|str|Description to use for the Namespace.| +|`company`|""|no|str|Namespace owner company name.| +|`email`|"password"|yes|str|Namespace contact email.| +|`avatar_url`|"public"|yes|str|Namespace logo URL.| +|`resources`|""|no|str|Namespace resource page in Markdown format.| +|`links`|[]|no|list|A list of dictionaries of Name and url values for links related the Namespace. See below for details.| +|`groups`|[]|yes|list|A list of dictionaries of the Names of groups that own the Namespace.| +|`state`|`present`|no|str|Desired state of the namespace.| + +#### Links + +|Variable Name|Default Value|Required|Type|Description| +|`name`|""|yes|str|Link Text.| +|`description`|""|yes|str|Link URL.| + +### Standard Project Data Structure + +#### Yaml Example + +```yaml +ah_namespaces: + - name: abc15 + company: Redhat + email: user@example.com + avatar_url: https://static.redhat.com/libs/redhat/brand-assets/latest/corp/logo.svg + description: string + resources: "# Redhat\nA Namespace test with changes" + links: + - name: "New_Google" + url: "http://www.google.com" + groups: + - name: system:partner-engineers + object_roles: + - "change_namespace" + - "upload_to_namespace" +``` + +## Playbook Examples + +### Standard Role Usage + +```yaml +- name: Add namespace to Automation Hub + hosts: localhost + connection: local + gather_facts: false + vars: + ah_validate_certs: false + # Define following vars here, or in ah_configs/ah_auth.yml + # ah_host: ansible-ah-web-svc-test-project.example.com + # ah_token: changeme + pre_tasks: + - name: Include vars from ah_configs directory + ansible.builtin.include_vars: + dir: ./vars + extensions: ["yml"] + tags: + - always + roles: + - ../../namespace +``` + +## License + +[GPLv3+](https://github.com/ansible/galaxy_collection#licensing) + +## Author + +[Sean Sullivan](https://github.com/sean-m-sullivan/) diff --git a/collections/ah_configuration/offline_sync.md b/collections/ah_configuration/offline_sync.md new file mode 100644 index 0000000..e16fe27 --- /dev/null +++ b/collections/ah_configuration/offline_sync.md @@ -0,0 +1,102 @@ +--- +layout: default +title: offline_sync +parent: infra.ah_configuration +--- + +# galaxy.galaxy.offline_sync + +## Description + +An Ansible Role to offline_sync collections to Automation Hub or Galaxies. NOTE: if you do not provide an ah_token one will be generated which will invalidate any prior token. + +## Variables + +|Variable Name|Default Value|Required|Description|Example| +|`ah_host`|""|yes|URL to the Automation Hub or Galaxy Server. (alias: `ah_hostname`)|127.0.0.1| +|`ah_username`|""|yes|Admin User on the Automation Hub or Galaxy Server.|| +|`ah_password`|""|yes|Automation Hub Admin User's password on the Automation Hub Server. This should be stored in an Ansible Vault at vars/tower-secrets.yml or elsewhere and called from a parent playbook.|| +|`ah_token`|""|no|Admin User's token on the Automation Hub Server. This should be stored in an Ansible Vault at or elsewhere and called from a parent playbook.|| +|`ah_validate_certs`|`true`|no|Whether or not to validate the Ansible Automation Hub Server's SSL certificate.|| +|`ah_request_timeout`|`10`|no|Specify the timeout Ansible should use in requests to the Galaxy or Automation Hub host.|| +|`ah_path_prefix`|""|no|API path used to access the api. Either galaxy, automation-hub, or custom|| + +### Asynchronous Retry Variables + +The following Variables set asynchronous retries for the role. +If neither of the retries or delay or retries are set, they will default to their respective defaults. +This allows for all items to be created, then checked that the task finishes successfully. +This also speeds up the overall role. + +|Variable Name|Default Value|Required|Description| +|`ah_configuration_async_retries`|50|no|This variable sets the number of retries to attempt for the role globally.| +|`ah_configuration_collection_async_retries`|`ah_configuration_async_retries`|no|This variable sets the number of retries to attempt for the role.| +|`ah_configuration_async_delay`|1|no|This sets the delay between retries for the role globally.| +|`ah_configuration_collection_async_delay`|`ah_configuration_async_delay`|no|This sets the delay between retries for the role.| + +## Data Structure + +### ah_collections Variables + +|Variable Name|Default Value|Required|Type|Description| +|`ah_configuration_working_dir`|`/var/tmp/pah_offline_sync`|no|string|The working directory where the collections will be downloaded and any required files.| +|`ah_configuration_no_deps`|false|no|bool|Whether to download all dependencies for each collection or not, if false it may cause errors if dependency sync is off in Automation Hub.| + +## Playbook Examples + +### Standard Role Usage + +```yaml +- name: Download all collections from Automation Hub + hosts: localhost + connection: local + gather_facts: false + vars: + ah_validate_certs: false + # Define following vars here, or in ah_configs/ah_auth.yml + # ah_host: ansible-ah-web-svc-test-project.example.com + # ah_token: changeme + pre_tasks: + - name: Include vars from ah_configs directory + ansible.builtin.include_vars: + dir: ./vars + extensions: ["yml"] + tags: + - always + roles: + - galaxy.galaxy.offline_sync +``` + +### Playbook to upload to offline Automation Hub after using this role to download the collections + +```yaml +- name: Upload all collections + hosts: localhost + gather_facts: false + connection: local + vars_files: + - "collections.yml" + pre_tasks: + - name: Include vars from ah_configs directory with collections.yml file added + ansible.builtin.include_vars: + dir: ./vars + extensions: ["yml"] + tags: + - always + tasks: + - name: Ensure the namespaces exists + ansible.builtin.import_role: + name: galaxy.galaxy.namespace + + - name: Upload collections + ansible.builtin.include_role: + name: galaxy.galaxy.collection +``` + +## License + +[GPLv3+](https://github.com/ansible/galaxy_collection#licensing) + +## Author + +[David Danielsson](https://github.com/djdanielsson) diff --git a/collections/ah_configuration/publish.md b/collections/ah_configuration/publish.md new file mode 100644 index 0000000..736cf87 --- /dev/null +++ b/collections/ah_configuration/publish.md @@ -0,0 +1,111 @@ +--- +layout: default +title: publish +parent: infra.ah_configuration +--- + +# galaxy.galaxy.publish + +## Description + +An Ansible Role to publish collections to Automation Hub or Galaxies. + +## Variables + +|Variable Name|Default Value|Required|Description|Example| +|`ah_host`|""|yes|URL to the Automation Hub or Galaxy Server. (alias: `ah_hostname`)|127.0.0.1| +|`ah_username`|""|yes|Admin User on the Automation Hub or Galaxy Server.|| +|`ah_password`|""|yes|Automation Hub Admin User's password on the Automation Hub Server. This should be stored in an Ansible Vault at vars/tower-secrets.yml or elsewhere and called from a parent playbook.|| +|`ah_token`|""|no|Admin User's token on the Automation Hub Server. This should be stored in an Ansible Vault at or elsewhere and called from a parent playbook.|| +|`ah_validate_certs`|`true`|no|Whether or not to validate the Ansible Automation Hub Server's SSL certificate.|| +|`ah_request_timeout`|`10`|no|Specify the timeout Ansible should use in requests to the Galaxy or Automation Hub host.|| +|`ah_path_prefix`|""|no|API path used to access the api. Either galaxy, automation-hub, or custom|| +|`ah_configuration_async_dir`|`null`|no|Sets the directory to write the results file for async tasks. The default value is set to `null` which uses the Ansible Default of `/root/.ansible_async/`.|| +|`ah_configuration_working_dir`|`/var/tmp`|no|The working directory where the built artifacts live, or where the artifacts will be built.|| +|`ah_auto_approve`|`False`|no|Whether the collection will be automatically approved in Automation Hub. This will only work if the account being used has correct privileges.|| +|`ah_overwrite_existing`|`False`|no|Whether the collection will be automatically overwrite an existing collection in Automation Hub. This will only work if the account being used has correct privileges.|| +|`ah_collections`|`see below`|no|Data structure describing your collections, mutually exclusive to ah_collection_list, described below.|| +|`ah_collection_list`|`list`|no|Data structure file paths to pre built collections, mutually exclusive with ah_collections.|| + +### Secure Logging Variables + +The following Variables compliment each other. +If Both variables are not set, secure logging defaults to false. +The role defaults to False as normally the add publish collections task does not include sensitive information. +ah_configuration_publish_secure_logging defaults to the value of ah_configuration_secure_logging if it is not explicitly called. This allows for secure logging to be toggled for the entire suite of automation hub configuration roles with a single variable, or for the user to selectively use it. + +|Variable Name|Default Value|Required|Description| +|`ah_configuration_publish_secure_logging`|`False`|no|Whether or not to include the sensitive publish collections role tasks in the log. Set this value to `True` if you will be providing your sensitive values from elsewhere.| +|`ah_configuration_secure_logging`|`False`|no|This variable enables secure logging as well, but is shared across multiple roles, see above.| + +### Asynchronous Retry Variables + +The following Variables set asynchronous retries for the role. +If neither of the retries or delay or retries are set, they will default to their respective defaults. +This allows for all items to be created, then checked that the task finishes successfully. +This also speeds up the overall role. + +|Variable Name|Default Value|Required|Description| +|`ah_configuration_async_timeout`|1000|no|This variable sets the async timeout for the role globally.| +|`ah_configuration_publish_async_timeout`|`ah_configuration_async_timeout`|no|This variable sets the async timeout for the role.| +|`ah_configuration_async_retries`|50|no|This variable sets the number of retries to attempt for the role globally.| +|`ah_configuration_publish_async_retries`|`ah_configuration_async_retries`|no|This variable sets the number of retries to attempt for the role.| +|`ah_configuration_async_delay`|1|no|This sets the delay between retries for the role globally.| +|`ah_configuration_publish_async_delay`|`ah_configuration_async_delay`|no|This sets the delay between retries for the role.| + +## Data Structure + +### ah_collections Variables + +|Variable Name|Default Value|Required|Type|Description| +|`collection_name`|""|yes|str|Name of collection, normally the last part before the / in a git url.| +|`git_url`|""|no|str|Url to git repo. Required if collection_local_path not set| +|`version`|""|no|str|Git ref to pull. Will default to default branch if unset. Can specify tag, branch or commit ref here.| +|`key_path`|""|no|str|Path to ssh key for authentication.| +|`ssh_opts`|""|no|str|Options git will pass to ssh when used as protocol.| +|`collection_local_path`|""|no|str|Path to collection stored locally. Required if git_url not set. This value will be used rather than git_url if set.| + +### Standard Project Data Structure + +#### Yaml Example + +```yaml +ah_collections: + - collection_name: cisco.iosxr + git_url: https://github.com/ansible-collections/cisco.iosxr + +ah_auto_approve: true +``` + +## Playbook Examples + +### Standard Role Usage + +```yaml +- name: Build and add collection to Automation Hub + hosts: localhost + connection: local + gather_facts: false + vars: + ah_validate_certs: false + # Define following vars here, or in ah_configs/ah_auth.yml + # ah_host: ansible-ah-web-svc-test-project.example.com + # ah_token: changeme + pre_tasks: + - name: Include vars from ah_configs directory + ansible.builtin.include_vars: + dir: ./vars + extensions: ["yml"] + tags: + - always + roles: + - galaxy.galaxy.publish +``` + +## License + +[GPLv3+](https://github.com/ansible/galaxy_collection#licensing) + +## Author + +[Sean Sullivan](https://github.com/sean-m-sullivan/) diff --git a/collections/ah_configuration/repository.md b/collections/ah_configuration/repository.md new file mode 100644 index 0000000..e19aa73 --- /dev/null +++ b/collections/ah_configuration/repository.md @@ -0,0 +1,130 @@ +--- +layout: default +title: repository +parent: infra.ah_configuration +--- + +# galaxy.galaxy.repository + +## Description + +An Ansible Role to create Repositories in Automation Hub. +This role has been depreciated and is not supported in AAP 2.4 onwards. It is replaced by collection_remote. + +## Variables + +|Variable Name|Default Value|Required|Description|Example| +|`ah_host`|""|yes|URL to the Automation Hub or Galaxy Server. (alias: `ah_hostname`)|127.0.0.1| +|`ah_username`|""|yes|Admin User on the Automation Hub or Galaxy Server.|| +|`ah_password`|""|yes|Automation Hub Admin User's password on the Automation Hub Server. This should be stored in an Ansible Vault at vars/tower-secrets.yml or elsewhere and called from a parent playbook.|| +|`ah_token`|""|yes|Tower Admin User's token on the Automation Hub Server. This should be stored in an Ansible Vault at or elsewhere and called from a parent playbook.|| +|`ah_validate_certs`|`true`|no|Whether or not to validate the Ansible Automation Hub Server's SSL certificate.|| +|`ah_request_timeout`|`10`|no|Specify the timeout Ansible should use in requests to the Galaxy or Automation Hub host.|| +|`ah_path_prefix`|""|no|API path used to access the api. Either galaxy, automation-hub, or custom|| +|`ah_configuration_async_dir`|`null`|no|Sets the directory to write the results file for async tasks. The default value is set to `null` which uses the Ansible Default of `/root/.ansible_async/`.|| +|`ah_repositories`|`see below`|yes|Data structure describing your namespaces, described below.|| + +The `ah_configuration_async_dir` variable sets the directory to write the results file for async tasks. +The default value is set to `null` which uses the Ansible Default of `/root/.ansible_async/`. + +### Secure Logging Variables + +The following Variables compliment each other. +If Both variables are not set, secure logging defaults to false. +The role defaults to False as normally the add repository task does not include sensitive information. +ah_configuration_repository_secure_logging defaults to the value of ah_configuration_secure_logging if it is not explicitly called. This allows for secure logging to be toggled for the entire suite of automation hub configuration roles with a single variable, or for the user to selectively use it. + +|Variable Name|Default Value|Required|Description| +|`ah_configuration_repository_secure_logging`|`False`|no|Whether or not to include the sensitive Namespace role tasks in the log. Set this value to `True` if you will be providing your sensitive values from elsewhere.| +|`ah_configuration_secure_logging`|`False`|no|This variable enables secure logging as well, but is shared across multiple roles, see above.| + +### Asynchronous Retry Variables + +The following Variables set asynchronous retries for the role. +If neither of the retries or delay or retries are set, they will default to their respective defaults. +This allows for all items to be created, then checked that the task finishes successfully. +This also speeds up the overall role. + +|Variable Name|Default Value|Required|Description| +|`ah_configuration_async_timeout`|1000|no|This variable sets the async timeout for the role globally.| +|`ah_configuration_repository_async_timeout`|`ah_configuration_async_timeout`|no|This variable sets the async timeout for the role.| +|`ah_configuration_async_retries`|50|no|This variable sets the number of retries to attempt for the role globally.| +|`ah_configuration_repository_async_retries`|`ah_configuration_async_retries`|no|This variable sets the number of retries to attempt for the role.| +|`ah_configuration_async_delay`|1|no|This sets the delay between retries for the role globally.| +|`ah_configuration_repository_async_delay`|`ah_configuration_async_delay`|no|This sets the delay between retries for the role.| + +## Data Structure + +### Repository Variables + +|Variable Name|Default Value|Required|Description|Example| +|`name`|""|yes| Repository name. Probably one of community, validated, or rh-certified|| +|`url`|`https://cloud.redhat.com/api/automation-hub/`|no|(`ah_repository_certified`)Remote URL for the repository.|`https://console.redhat.com/api/automation-hub/content/`| +|`url`|`https://galaxy.ansible.com/api/`|no|(`ah_repository_community`)Remote URL for the repository.|| +|`auth_url`|`https://sso.redhat.com/auth/realms/redhat-external/protocol/openid-connect/token`|no|(`ah_repository_certified`)Remote URL for the repository authentication if separate.|| +|`token`|""|no|Token to authenticate to the remote repository.|| +|`username`|""|no|Username to authenticate to the remote repository.|| +|`password`|""|no|Password to authenticate to the remote repository.|| +|`requirements`|""|no|(`ah_repository_community`)Requirements to download from remote.|| +|`requirements_file`|""|no|(`ah_repository_community`)A yaml requirements file to download from remote.|| +|`proxy_url`|""|no|The URL for the proxy. Defaults to global `proxy_url` variable.|| +|`proxy_username`|""|no|The username for the proxy authentication. Defaults to global `proxy_username` variable.|| +|`proxy_password`|""|no|The password for the proxy authentication. Defaults to global `proxy_password` variable.|| +|`ah_token`|""|yes|Tower Admin User's token on the Automation Hub Server. This should be stored in an Ansible Vault at or elsewhere and called from a parent playbook.|| +|`download_concurrency`|"10"|no| Number of concurrent collections to download.|| +|`rate_limit`|"8"|no|Limits total download rate in requests per second|| +|`signed_only`|"False"|no|Only download signed collections|True| +|`tls_validation`|"True"|no|Whether to use TLS validation against the remote repository|False| +|`client_key`|""|no|A PEM encoded private key file used for authentication|| +|`client_cert`|""|no|A PEM encoded client certificate used for authentication|| +|`ca_cert`|""|no|A PEM encoded CA certificate used for authentication|| +|`client_key_path`|""|no|Path to a PEM encoded private key file used for authentication|| +|`client_cert_path`|""|no|Path to a PEM encoded client certificate used for authentication|| +|`ca_cert_path`|""|no|Path to a PEM encoded CA certificate used for authentication|| + +#### Yaml Example + +```yaml +ah_repositories: + - name: community + url: https://beta-galaxy.ansible.com/ + requirements: + - name: infra.ee_utilities + - name: infra.controller_configuration + wait: true + interval: 25 + timeout: 1000000 +``` + +## Playbook Examples + +### Standard Role Usage + +```yaml +- name: Add repository to Automation Hub + hosts: localhost + connection: local + gather_facts: false + vars: + ah_validate_certs: false + # Define following vars here, or in ah_configs/ah_auth.yml + # ah_host: ansible-ah-web-svc-test-project.example.com + # ah_token: changeme + pre_tasks: + - name: Include vars from ah_configs directory + ansible.builtin.include_vars: + dir: ./vars + extensions: ["yml"] + tags: + - always + roles: + - ../../repository +``` + +## License + +[GPLv3+](https://github.com/ansible/galaxy_collection#licensing) + +## Author + +[Inderpal Tiwana](https://github.com/inderpaltiwana/) and [David Danielsson](https://github.com/djdanielsson) diff --git a/collections/ah_configuration/repository_sync.md b/collections/ah_configuration/repository_sync.md new file mode 100644 index 0000000..61e5822 --- /dev/null +++ b/collections/ah_configuration/repository_sync.md @@ -0,0 +1,106 @@ +--- +layout: default +title: repository_sync +parent: infra.ah_configuration +--- + +# galaxy.galaxy.repository_sync + +## Description + +An Ansible Role to sync Repositories in Automation Hub. +This role has been depreciated and is not supported in AAP 2.4 onwards. It is replaced by collection_remote_sync. + +## Variables + +|Variable Name|Default Value|Required|Description|Example| +|`ah_host`|""|yes|URL to the Automation Hub or Galaxy Server. (alias: `ah_hostname`)|127.0.0.1| +|`ah_username`|""|yes|Admin User on the Automation Hub or Galaxy Server.|| +|`ah_password`|""|yes|Automation Hub Admin User's password on the Automation Hub Server. This should be stored in an Ansible Vault at vars/tower-secrets.yml or elsewhere and called from a parent playbook.|| +|`ah_token`|""|yes|Tower Admin User's token on the Automation Hub Server. This should be stored in an Ansible Vault at or elsewhere and called from a parent playbook.|| +|`ah_validate_certs`|`true`|no|Whether or not to validate the Ansible Automation Hub Server's SSL certificate.|| +|`ah_request_timeout`|`10`|no|Specify the timeout Ansible should use in requests to the Galaxy or Automation Hub host.|| +|`ah_path_prefix`|""|no|API path used to access the api. Either galaxy, automation-hub, or custom|| +|`ah_configuration_async_dir`|`null`|no|Sets the directory to write the results file for async tasks. The default value is set to `null` which uses the Ansible Default of `/root/.ansible_async/`.|| +|`ah_repositories`|`see below`|yes|Data structure describing your namespaces, described below.|| + +The `ah_configuration_async_dir` variable sets the directory to write the results file for async tasks. +The default value is set to `null` which uses the Ansible Default of `/root/.ansible_async/`. + +### Secure Logging Variables + +The following Variables compliment each other. +If Both variables are not set, secure logging defaults to false. +The role defaults to False as normally the add repository task does not include sensitive information. +ah_configuration_repository_secure_logging defaults to the value of ah_configuration_secure_logging if it is not explicitly called. This allows for secure logging to be toggled for the entire suite of automation hub configuration roles with a single variable, or for the user to selectively use it. + +|Variable Name|Default Value|Required|Description| +|`ah_configuration_repository_secure_logging`|`False`|no|Whether or not to include the sensitive Repository roles tasks in the log. Set this value to `True` if you will be providing your sensitive values from elsewhere.| +|`ah_configuration_secure_logging`|`False`|no|This variable enables secure logging as well, but is shared across multiple roles, see above.| + +### Asynchronous Retry Variables + +The following Variables set asynchronous retries for the role. +If neither of the retries or delay or retries are set, they will default to their respective defaults. +This allows for all items to be created, then checked that the task finishes successfully. +This also speeds up the overall role. + +|Variable Name|Default Value|Required|Description| +|`ah_configuration_async_timeout`|1000|no|This variable sets the async timeout for the role globally.| +|`ah_configuration_repository_sync_async_timeout`|`ah_configuration_async_timeout`|no|This variable sets the async timeout for the role.| +|`ah_configuration_async_retries`|50|no|This variable sets the number of retries to attempt for the role globally.| +|`ah_configuration_repository_sync_async_retries`|`ah_configuration_async_retries`|no|This variable sets the number of retries to attempt for the role.| +|`ah_configuration_async_delay`|1|no|This sets the delay between retries for the role globally.| +|`ah_configuration_repository_sync_async_delay`|`ah_configuration_async_delay`|no|This sets the delay between retries for the role.| + +## Data Structure + +### Repository Variables + +|Variable Name|Default Value|Required|Description|Example| +|`name`|""|yes| Repository name. Probably one of community, validated, or rh-certified.|| +|`wait`|"false"|no|Wait for the repository to finish syncing before returning.|| +|`interval`|"1"|no|The interval to request an update from Automation Hub.|| +|`timeout`|""|no|If waiting for the project to update this will abort after this amount of seconds.|| + +### Standard Project Data Structure + +#### Yaml Example + +```yaml +ah_repositories: + - name: community +``` + +## Playbook Examples + +### Standard Role Usage + +```yaml +- name: Add repository to Automation Hub + hosts: localhost + connection: local + gather_facts: false + vars: + ah_validate_certs: false + # Define following vars here, or in ah_configs/ah_auth.yml + # ah_host: ansible-ah-web-svc-test-project.example.com + # ah_token: changeme + pre_tasks: + - name: Include vars from ah_configs directory + ansible.builtin.include_vars: + dir: ./vars + extensions: ["yml"] + tags: + - always + roles: + - ../../repository_sync +``` + +## License + +[GPLv3+](https://github.com/ansible/galaxy_collection#licensing) + +## Author + +[Inderpal Tiwana](https://github.com/inderpaltiwana/) and [David Danielsson](https://github.com/djdanielsson) diff --git a/collections/ah_configuration/role.md b/collections/ah_configuration/role.md new file mode 100644 index 0000000..b685978 --- /dev/null +++ b/collections/ah_configuration/role.md @@ -0,0 +1,127 @@ +--- +layout: default +title: role +parent: infra.ah_configuration +--- + +# galaxy.galaxy.role + +## Description + +An Ansible Role to create role permissions in Automation Hub. + +## Variables + +|Variable Name|Default Value|Required|Description|Example| +|`ah_host`|""|yes|URL to the Automation Hub or Galaxy Server. (alias: `ah_hostname`)|127.0.0.1| +|`ah_username`|""|yes|Admin User on the Automation Hub or Galaxy Server.|| +|`ah_password`|""|yes|Automation Hub Admin User's password on the Automation Hub Server. This should be stored in an Ansible Vault at vars/tower-secrets.yml or elsewhere and called from a parent playbook.|| +|`ah_validate_certs`|`true`|no|Whether or not to validate the Ansible Automation Hub Server's SSL certificate.|| +|`ah_request_timeout`|`10`|no|Specify the timeout Ansible should use in requests to the Galaxy or Automation Hub host.|| +|`ah_path_prefix`|""|no|API path used to access the api. Either galaxy, automation-hub, or custom|| +|`ah_configuration_async_dir`|`null`|no|Sets the directory to write the results file for async tasks. The default value is set to `null` which uses the Ansible Default of `/root/.ansible_async/`.|| +|`ah_roles`|`see below`|yes|Data structure describing your role permissions, described below.|| + +### Secure Logging Variables + +The following Variables compliment each other. +If Both variables are not set, secure logging defaults to false. +The role defaults to False as normally the add group task does not include sensitive information. +ah_configuration_group_secure_logging defaults to the value of ah_configuration_secure_logging if it is not explicitly called. This allows for secure logging to be toggled for the entire suite of automation hub configuration roles with a single variable, or for the user to selectively use it. + +|Variable Name|Default Value|Required|Description| +|`ah_configuration_role_secure_logging`|`False`|no|Whether or not to include the sensitive Namespace role tasks in the log. Set this value to `True` if you will be providing your sensitive values from elsewhere.| +|`ah_configuration_secure_logging`|`False`|no|This variable enables secure logging as well, but is shared across multiple roles, see above.| + +### Asynchronous Retry Variables + +The following Variables set asynchronous retries for the role. +If neither of the retries or delay or retries are set, they will default to their respective defaults. +This allows for all items to be created, then checked that the task finishes successfully. +This also speeds up the overall role. + +|Variable Name|Default Value|Required|Description| +|`ah_configuration_async_timeout`|1000|no|This variable sets the async timeout for the role globally.| +|`ah_configuration_role_async_timeout`|`ah_configuration_async_timeout`|no|This variable sets the async timeout for the role.| +|`ah_configuration_async_retries`|50|no|This variable sets the number of retries to attempt for the role globally.| +|`ah_configuration_role_async_retries`|`ah_configuration_async_retries`|no|This variable sets the number of retries to attempt for the role.| +|`ah_configuration_async_delay`|1|no|This sets the delay between retries for the role globally.| +|`ah_configuration_role_async_delay`|`ah_configuration_async_delay`|no|This sets the delay between retries for the role.| + +## Data Structure + +### Role Variables + +|Variable Name|Default Value|Required|Type|Description| +|`name`|""|yes|str|Group Name. Must be lower case containing only alphanumeric characters and underscores. Must start with 'galaxy.'.| +|`description`|""|yes|str|The description of the permission role.| +|`perms`|""|yes|str|The list of permissions for the given role. See below for options.| +|`state`|`present`|no|str|Desired state of the group.| + +#### perms + +The module accepts the following roles: + +- For user management, `add_user`, `change_user`, `delete_user`, and `view_user`. +- For group management, `add_group`, `change_group`, `delete_group`, and `view_group`. +- For collection namespace management, `add_namespace`, `change_namespace`, `upload_to_namespace`, and `delete_namespace`. +- For collection content management, `modify_ansible_repo_content`, `delete_collection`, and `sign_ansiblerepository`. +- For remote repository configuration, `change_collectionremote`, `view_collectionremote`, + `add_collectionremote`, `delete_collectionremote`, and `manage_roles_collectionremote`. +- For Ansible Repository management, only with private automation hub v4.7.0 + `add_ansiblerepository`, `change_ansiblerepository`, `delete_ansiblerepository`, `manage_roles_ansiblerepository`, + `repair_ansiblerepository`, `view_ansiblerepository`, +- For container image management, only with private automation hub v4.3.2 or later, + `change_containernamespace_perms`, `change_container`, `change_image_tag`, `create_container`, + Push existing container `push_container`, `namespace_add_containerdistribution`, `manage_roles_containernamespace`, + and `delete_containerrepository`. +- For remote registry management, `add_containerregistryremote`, `change_containerregistryremote`, and`delete_containerregistryremote`. +- For task management, `change_task`, `view_task`, and `delete_task`. +- You can also grant or revoke all permissions with `*` or `all`. + +### Standard Project Data Structure + +#### Yaml Example + +```yaml +ah_roles: + - name: galaxy.stuff.mcstuffins + description: test + perms: + - add_user + - change_user + - delete_user + - view_user +``` + +## Playbook Examples + +### Standard Role Usage + +```yaml +- name: Add roles to Automation Hub + hosts: localhost + connection: local + gather_facts: false + vars: + ah_validate_certs: false + # Define following vars here, or in ah_configs/ah_auth.yml + # ah_host: ansible-ah-web-svc-test-project.example.com + pre_tasks: + - name: Include vars from ah_configs directory + ansible.builtin.include_vars: + dir: ./vars + extensions: ["yml"] + tags: + - always + roles: + - ../../role +``` + +## License + +[GPLv3+](https://github.com/ansible/galaxy_collection#licensing) + +## Author + +[Tom Page](https://github.com/Tompage1994/) diff --git a/collections/ah_configuration/user.md b/collections/ah_configuration/user.md new file mode 100644 index 0000000..54914b3 --- /dev/null +++ b/collections/ah_configuration/user.md @@ -0,0 +1,115 @@ +--- +layout: default +title: user +parent: infra.ah_configuration +--- + +# galaxy.galaxy.user + +## Description + +An Ansible Role to create users in Automation Hub. + +## Variables + +|Variable Name|Default Value|Required|Description|Example| +|`ah_host`|""|yes|URL to the Automation Hub or Galaxy Server. (alias: `ah_hostname`)|127.0.0.1| +|`ah_username`|""|yes|Admin User on the Automation Hub or Galaxy Server.|| +|`ah_password`|""|yes|Automation Hub Admin User's password on the Automation Hub Server. This should be stored in an Ansible Vault at vars/tower-secrets.yml or elsewhere and called from a parent playbook.|| +|`ah_validate_certs`|`true`|no|Whether or not to validate the Ansible Automation Hub Server's SSL certificate.|| +|`ah_request_timeout`|`10`|no|Specify the timeout Ansible should use in requests to the Galaxy or Automation Hub host.|| +|`ah_path_prefix`|""|no|API path used to access the api. Either galaxy, automation-hub, or custom|| +|`ah_configuration_async_dir`|`null`|no|Sets the directory to write the results file for async tasks. The default value is set to `null` which uses the Ansible Default of `/root/.ansible_async/`.|| +|`ah_users`|`see below`|yes|Data structure describing your execution environment images, described below.|| + +### Secure Logging Variables + +The following Variables compliment each other. +If Both variables are not set, secure logging defaults to false. +The role defaults to False as normally the add user task does not include sensitive information. +ah_configuration_user_secure_logging defaults to the value of ah_configuration_secure_logging if it is not explicitly called. This allows for secure logging to be toggled for the entire suite of automation hub configuration roles with a single variable, or for the user to selectively use it. + +|Variable Name|Default Value|Required|Description| +|`ah_configuration_user_secure_logging`|`False`|no|Whether or not to include the sensitive Namespace role tasks in the log. Set this value to `True` if you will be providing your sensitive values from elsewhere.| +|`ah_configuration_secure_logging`|`False`|no|This variable enables secure logging as well, but is shared across multiple roles, see above.| + +### Asynchronous Retry Variables + +The following Variables set asynchronous retries for the role. +If neither of the retries or delay or retries are set, they will default to their respective defaults. +This allows for all items to be created, then checked that the task finishes successfully. +This also speeds up the overall role. + +|Variable Name|Default Value|Required|Description| +|`ah_configuration_async_timeout`|1000|no|This variable sets the async timeout for the role globally.| +|`ah_configuration_user_async_timeout`|`ah_configuration_async_timeout`|no|This variable sets the async timeout for the role.| +|`ah_configuration_async_retries`|50|no|This variable sets the number of retries to attempt for the role globally.| +|`ah_configuration_user_async_retries`|`ah_configuration_async_retries`|no|This variable sets the number of retries to attempt for the role.| +|`ah_configuration_async_delay`|1|no|This sets the delay between retries for the role globally.| +|`ah_configuration_user_async_delay`|`ah_configuration_async_delay`|no|This sets the delay between retries for the role.| + +## Data Structure + +### User Variables + +|Variable Name|Default Value|Required|Type|Description| +|`username`|""|yes|str|Username. Must be lower case containing only alphanumeric characters and underscores.| +|`groups`|[]|no|list|List of the groups to update.| +|`append`|true|no|str|Whether to append or replace the group list provided.| +|`first_name`|""|no|str|User's first name.| +|`last_name`|""|no|str|User's last name.| +|`email`|""|no|str|User's email address.| +|`is_superuser`|false|no|bool|Whether the user is a superuser.| +|`password`|""|no|str|User's password as a clear string. The password must contain at least 9 characters with numbers or special characters.| +|`state`|`present`|no|str|Desired state of the user.| + + +### Standard Project Data Structure + +#### Yaml Example + +```yaml +ah_users: + - username: user1 + groups: + - group1 + append: true + first_name: user + last_name: one + email: user1@example.com + is_superuser: false + password: p4ssword + state: present +``` + +## Playbook Examples + +### Standard Role Usage + +```yaml +- name: Add user to Automation Hub + hosts: localhost + connection: local + gather_facts: false + vars: + ah_validate_certs: false + # Define following vars here, or in ah_configs/ah_auth.yml + # ah_host: ansible-ah-web-svc-test-project.example.com + pre_tasks: + - name: Include vars from ah_configs directory + ansible.builtin.include_vars: + dir: ./vars + extensions: ["yml"] + tags: + - always + roles: + - ../../user +``` + +## License + +[GPLv3+](https://github.com/ansible/galaxy_collection#licensing) + +## Author + +[Tom Page](https://github.com/Tompage1994/) diff --git a/collections/controller_configuration/ansible_config.md b/collections/controller_configuration/ansible_config.md new file mode 100644 index 0000000..077b6f3 --- /dev/null +++ b/collections/controller_configuration/ansible_config.md @@ -0,0 +1,115 @@ +--- +layout: default +title: ansible_config +parent: infra.controller_configuration +--- + +# galaxy.galaxy.ansible_config + +## Description + +An Ansible Role to create ansible.cfg files based on your Automation Hub servers + +## Requirements + +ansible-galaxy collection install -r tests/collections/requirements.yml to be installed +Currently: + awx.awx + +## Variables + +|Variable Name|Default Value|Required|Description|Example| +|`ansible_config_mode`|'0644'|no|str|The permissions the resulting ansible config file or directory should have.| +|`ansible_config_owner`|""|no|str|The owner the resulting ansible config file or directory should have.| +|`ansible_config_group`|""|no|str|The group the resulting ansible config file or directory should have.| +|`aap_configuration_working_dir`|"/var/tmp"|no|path|Location to render the ansible config file to.| +|`automation_hub_list`|`[]`|no|list|A list of Automation hubs and galaxies to put in the ansible config, see below for details.| +|`ansible_config_list`|`[{"header":"galaxy","keypairs":[{"key":"ignore_certs","value":"{{ not (aap_validate_certs \| bool) }}"}]}]`|no|list|A set of ansible config settings, a default is set, but can be overridden, see below for details.| +|`ah_token`|""|no|Tower Admin User's token on the Automation Hub Server. This should be stored in an Ansible Vault at or elsewhere and called from a parent playbook.|| +|`ah_path_prefix`|`galaxy`|no|Tower Admin User's token on the Automation Hub Server. This should be stored in an Ansible Vault at or elsewhere and called from a parent playbook.|| + +### Secure Logging Variables + +The following Variables compliment each other. +If Both variables are not set, secure logging defaults to false. +The role defaults to False as normally the ansible config task does not by default include sensitive information, we highly recommend the use of ansible vault for passwords and tokens. +aap_configuration_ansible_config_secure_logging defaults to the value of aap_configuration_secure_logging if it is not explicitly called. This allows for secure logging to be toggled for the entire suite of automation hub configuration roles with a single variable, or for the user to selectively use it. + +|Variable Name|Default Value|Required|Description| +|`aap_configuration_ansible_config_secure_logging`|`False`|no|Whether or not to include the sensitive ansible config role tasks in the log. Set this value to `True` if you will be providing your sensitive values from elsewhere.| +|`aap_configuration_secure_logging`|`False`|no|This variable enables secure logging as well, but is shared across multiple roles, see above.| + +## Data Structures + +### automation_hub_list + +|Variable Name|Default Value|Required|Type|Description| +|`name`|""|yes|str|Name of the Automation Hub or Galaxy Server.| +|`url`|""|yes|str|URL to the Automation Hub or Galaxy Server| +|`auth_url`|""|no|str|URL to the authentication for Automation Hub or Galaxy Server| +|`token`|""|no|str|Automation Hub or Galaxy Server token.| + +### ansible_config_list + +|Variable Name|Default Value|Required|Type|Description| +|`header`|""|yes|str|Header of the section that contains keypairs.| +|`keypairs`|`[]`|no|list|List key value pairs for settings in the ansible.cfg.| + +### ansible_config_list[].keypairs + +|Variable Name|Default Value|Required|Type|Description| +|`key`|""|yes|str|Key for entry under this header.| +|`value`|""|yes|str|Value for entry for the corresponding key.| + +### Standard Project Data Structure + +#### Yaml Example + +```yaml +ansible_config_list: + - header: galaxy + keypairs: + - key: ignore_certs + value: "{{ not (aap_validate_certs | bool) }}" + - key: server_list + value: "{{ automation_hub_list }}" + +automation_hub_list: + - name: automation_hub + url: "{{ah_host}}/api/automation-hub/content/0000001-synclist/" + auth_url: https://sso.redhat.com/auth/realms/redhat-external/protocol/openid-connect/token + token: changeme +``` + +## Playbook Examples + +### Standard Role Usage + +```yaml +- name: Set up Ansible Configuration for usage with PAH + hosts: localhost + connection: local + gather_facts: false + vars: + aap_validate_certs: false + # Define following vars here, or in ah_configs/ah_auth.yml + # ah_host: ansible-ah-web-svc-test-project.example.com + # ah_token: changeme + pre_tasks: + - name: Include vars from ah_configs directory + ansible.builtin.include_vars: + dir: ./vars + extensions: ["yml"] + tags: + - always + roles: + - ../../ansible_config +``` + +## License + +[GPLv3+](https://github.com/ansible/galaxy_collection#licensing) + +## Author + +[Sean Sullivan](https://github.com/sean-m-sullivan/) diff --git a/collections/controller_configuration/controller_ad_hoc_command.md b/collections/controller_configuration/controller_ad_hoc_command.md new file mode 100644 index 0000000..37e9be2 --- /dev/null +++ b/collections/controller_configuration/controller_ad_hoc_command.md @@ -0,0 +1,108 @@ +--- +layout: default +title: controller_ad_hoc_command +parent: infra.controller_configuration +--- + +# controller_configuration.ad_hoc_command + +## Description + +An Ansible Role to run a list of ad hoc commands on Ansible Controller. + +## Requirements + +ansible-galaxy collection install -r tests/collections/requirements.yml to be installed +Currently: + awx.awx + or + ansible.controller + +## Variables + +|Variable Name|Default Value|Required|Description|Example| +|`platform_state`|"present"|no|The state all objects will take unless overridden by object default|'absent'| +|`aap_hostname`|""|yes|URL to the Ansible Automation Platform Server.|127.0.0.1| +|`aap_validate_certs`|`True`|no|Whether or not to validate the Ansible Automation Platform Server's SSL certificate.|| +|`aap_username`|""|no|Admin User on the Ansible Automation Platform Server. Either username / password or oauthtoken need to be specified.|| +|`aap_password`|""|no|Platform Admin User's password on the Server. This should be stored in an Ansible Vault at vars/platform-secrets.yml or elsewhere and called from a parent playbook.|| +|`aap_token`|""|no|Controller Admin User's token on the Ansible Automation Platform Server. This should be stored in an Ansible Vault at or elsewhere and called from a parent playbook. Either username / password or oauthtoken need to be specified.|| +|`aap_request_timeout`|`10`|no|Specify the timeout in seconds Ansible should use in requests to the Ansible Automation Platform host.|| +|`controller_ad_hoc_commands`|`see below`|yes|Data structure describing your ad hoc commands to run Described below.|| + +### Secure Logging Variables + +The following Variables compliment each other. +If Both variables are not set, secure logging defaults to false. +The role defaults to False as normally the add ad hoc commands task does not include sensitive information. +controller_configuration_ad_hoc_command_secure_logging defaults to the value of aap_configuration_secure_logging if it is not explicitly called. This allows for secure logging to be toggled for the entire suite of controller configuration roles with a single variable, or for the user to selectively use it. + +|Variable Name|Default Value|Required|Description| +|`controller_configuration_ad_hoc_command_secure_logging`|`False`|no|Whether or not to include the sensitive ad_hoc_command role tasks in the log. Set this value to `True` if you will be providing your sensitive values from elsewhere.| +|`aap_configuration_secure_logging`|`False`|no|This variable enables secure logging as well, but is shared across multiple roles, see above.| + +## Data Structure + +### Ad Hoc Command Variables + +|Variable Name|Default Value|Required|Type|Description| +|`job_type`|"run"|no|str|Job_type to use for the ad hoc command. Either run or check.| +|`inventory`|""|yes|str|Inventory to use for the ad hoc command.| +|`limit`|`False`|no|str|Limit to use for the ad hoc command.| +|`credential`|""|yes|str|Credential to use for ad hoc command.| +|`execution_environment`|""|no|str|Execution Environment to use for ad hoc command.| +|`module_name`|""|str|yes|The Ansible module to execute.| +|`module_args`|`False`|no|str|The arguments to pass to the module.| +|`forks`|0|yes|int|The number of forks to use for this ad hoc execution.| +|`verbosity`|0|no|int|Verbosity level for this ad hoc command run| +|`extra_vars`|`False`|no|dict|Extra variables to use for the ad hoc command.| +|`become_enabled`|""|no|bool|If the become flag should be set.| +|`diff_mode`|""|no|bool|Show the changes made by Ansible tasks where supported| +|`wait`|`False`|no|bool|Wait for the command to complete.| +|`interval`|2|no|int|The interval to request an update from controller.| +|`timeout`|""|no|int|If waiting for the command to complete this will abort after this amount of seconds.| + +### Standard Ad Hoc Command Data Structure + +#### Yaml Example + +```yaml +controller_ad_hoc_commands: + - job_type: run + inventory: localhost + credential: Demo Credential + module_name: ping + + +``` + +## Playbook Examples + +### Standard Role Usage + +```yaml +- name: Playbook to configure ansible controller post installation + hosts: localhost + connection: local + # Define following vars here, or in platform_configs/controller_auth.yml + # aap_hostname: ansible-controller-web-svc-test-project.example.com + # aap_username: admin + # aap_password: changeme + pre_tasks: + - name: Include vars from platform_configs directory + ansible.builtin.include_vars: + dir: ./yaml + ignore_files: [controller_config.yml.template] + extensions: ["yml"] + roles: + - {role: infra.aap_configuration.ad_hoc_command, when: controller_ad_hoc_commands is defined} + +``` + +## License + +[GPL-3.0](https://github.com/redhat-cop/aap_configuration#licensing) + +## Author + +[Sean Sullivan](https://github.com/sean-m-sullivan) diff --git a/collections/controller_configuration/controller_ad_hoc_command_cancel.md b/collections/controller_configuration/controller_ad_hoc_command_cancel.md new file mode 100644 index 0000000..a1840f9 --- /dev/null +++ b/collections/controller_configuration/controller_ad_hoc_command_cancel.md @@ -0,0 +1,99 @@ +--- +layout: default +title: controller_ad_hoc_command_cancel +parent: infra.controller_configuration +--- + +# controller_configuration.ad_hoc_command_cancel + +## Description + +An Ansible Role to cancel a list of ad hoc commands on Ansible Controller. + +## Requirements + +ansible-galaxy collection install -r tests/collections/requirements.yml to be installed +Currently: + awx.awx + or + ansible.controller + +## Variables + +|Variable Name|Default Value|Required|Description|Example| +|`platform_state`|"present"|no|The state all objects will take unless overridden by object default|'absent'| +|`aap_hostname`|""|yes|URL to the Ansible Automation Platform Server.|127.0.0.1| +|`aap_validate_certs`|`True`|no|Whether or not to validate the Ansible Automation Platform Server's SSL certificate.|| +|`aap_username`|""|no|Admin User on the Ansible Automation Platform Server. Either username / password or oauthtoken need to be specified.|| +|`aap_password`|""|no|Platform Admin User's password on the Server. This should be stored in an Ansible Vault at vars/platform-secrets.yml or elsewhere and called from a parent playbook.|| +|`aap_token`|""|no|Controller Admin User's token on the Ansible Automation Platform Server. This should be stored in an Ansible Vault at or elsewhere and called from a parent playbook. Either username / password or oauthtoken need to be specified.|| +|`aap_request_timeout`|`10`|no|Specify the timeout in seconds Ansible should use in requests to the Ansible Automation Platform host.|| +|`controller_ad_hoc_commands_cancel`|`see below`|yes|Data structure describing your ad hoc jobs to cancel Described below.|| + +### Secure Logging Variables + +The following Variables compliment each other. +If Both variables are not set, secure logging defaults to false. +The role defaults to False as normally the add ad hoc commands cancel task does not include sensitive information. +controller_configuration_ad_hoc_command_secure_logging defaults to the value of aap_configuration_secure_logging if it is not explicitly called. This allows for secure logging to be toggled for the entire suite of controller configuration roles with a single variable, or for the user to selectively use it. + +|Variable Name|Default Value|Required|Description| +|`controller_configuration_ad_hoc_command_cancel_secure_logging`|`False`|no|Whether or not to include the sensitive ad_hoc_command_cancel role tasks in the log. Set this value to `True` if you will be providing your sensitive values from elsewhere.| +|`aap_configuration_secure_logging`|`False`|no|This variable enables secure logging as well, but is shared across multiple roles, see above.| + +## Data Structure + +### Ad Hoc Command Cancel Variables + +|Variable Name|Default Value|Required|Type|Description| +|`id`|""|yes|int|ID of the command to cancel Recommended to be in a separate list of ID's see example, defaults to output of ad_hoc_command_role of controller_ad_hoc_commands_output.| +|`fail_if_not_running`|`False`|no|bool|Fail loudly if the I(command_id) can not be canceled.| +|`interval`|1|no|int|The interval in seconds, to request an update from.| +|`timeout`|0|no|int|Maximum time in seconds to wait for a job to finish, 0 means wait until it is finished regardless.| + +### Standard Ad Hoc Command Cancel Data Structure + +#### Yaml Example + +```yaml +controller_ad_hoc_commands_cancel: + - id: 10 + fail_if_not_running: false + interval: 1 + timeout: 10 + - id: 12 + fail_if_not_running: false + interval: 1 + timeout: 10 + +``` + +## Playbook Examples + +### Standard Role Usage + +```yaml +- name: Playbook to configure ansible controller post installation + hosts: localhost + connection: local + # Define following vars here, or in platform_configs/controller_auth.yml + # aap_hostname: ansible-controller-web-svc-test-project.example.com + # aap_username: admin + # aap_password: changeme + pre_tasks: + - name: Include vars from platform_configs directory + ansible.builtin.include_vars: + dir: ./yaml + ignore_files: [controller_config.yml.template] + extensions: ["yml"] + roles: + - {role: infra.aap_configuration.ad_hoc_command_cancel, when: controller_ad_hoc_commands is defined} +``` + +## License + +[GPL-3.0](https://github.com/redhat-cop/aap_configuration#licensing) + +## Author + +[Sean Sullivan](https://github.com/sean-m-sullivan) diff --git a/collections/controller_configuration/controller_applications.md b/collections/controller_configuration/controller_applications.md new file mode 100644 index 0000000..51e3f58 --- /dev/null +++ b/collections/controller_configuration/controller_applications.md @@ -0,0 +1,149 @@ +--- +layout: default +title: controller_applications +parent: infra.controller_configuration +--- + +# controller_configuration.applications + +## Description + +An Ansible Role to create/update/remove Applications on Ansible Controller. + +## Requirements + +ansible-galaxy collection install -r tests/collections/requirements.yml to be installed +Currently: + awx.awx + or + ansible.controller + +## Variables + +|Variable Name|Default Value|Required|Description|Example| +|`platform_state`|"present"|no|The state all objects will take unless overridden by object default|'absent'| +|`aap_hostname`|""|yes|URL to the Ansible Automation Platform Server.|127.0.0.1| +|`aap_validate_certs`|`True`|no|Whether or not to validate the Ansible Automation Platform Server's SSL certificate.|| +|`aap_username`|""|no|Admin User on the Ansible Automation Platform Server. Either username / password or oauthtoken need to be specified.|| +|`aap_password`|""|no|Platform Admin User's password on the Server. This should be stored in an Ansible Vault at vars/platform-secrets.yml or elsewhere and called from a parent playbook.|| +|`aap_token`|""|no|Controller Admin User's token on the Ansible Automation Platform Server. This should be stored in an Ansible Vault at or elsewhere and called from a parent playbook. Either username / password or oauthtoken need to be specified.|| +|`aap_request_timeout`|`10`|no|Specify the timeout in seconds Ansible should use in requests to the Ansible Automation Platform host.|| +|`aap_applications`|`see below`|yes|Data structure describing your applications, described below. Alias: applications || + +### Enforcing defaults + +The following Variables compliment each other. +If Both variables are not set, enforcing default values is not done. +Enabling these variables enforce default values on options that are optional in the controller API. +This should be enabled to enforce configuration and prevent configuration drift. It is recomended to be enabled, however it is not enforced by default. + +Enabling this will enforce configurtion without specifying every option in the configuration files. + +'controller_configuration_applications_enforce_defaults' defaults to the value of 'aap_configuration_enforce_defaults' if it is not explicitly called. This allows for enforced defaults to be toggled for the entire suite of controller configuration roles with a single variable, or for the user to selectively use it. + +|Variable Name|Default Value|Required|Description| +|`controller_configuration_applications_enforce_defaults`|`False`|no|Whether or not to enforce default option values on only the applications role| +|`aap_configuration_enforce_defaults`|`False`|no|This variable enables enforced default values as well, but is shared across multiple roles, see above.| + +### Secure Logging Variables + +The following Variables compliment each other. +If Both variables are not set, secure logging defaults to false. +The role defaults to False as normally the add application task does not include sensitive information. +controller_configuration_applications_secure_logging defaults to the value of aap_configuration_secure_logging if it is not explicitly called. This allows for secure logging to be toggled for the entire suite of controller configuration roles with a single variable, or for the user to selectively use it. + +|Variable Name|Default Value|Required|Description| +|`controller_configuration_applications_secure_logging`|`False`|no|Whether or not to include the sensitive Application role tasks in the log. Set this value to `True` if you will be providing your sensitive values from elsewhere.| +|`aap_configuration_secure_logging`|`False`|no|This variable enables secure logging as well, but is shared across multiple roles, see above.| + +### Asynchronous Retry Variables + +The following Variables set asynchronous retries for the role. +If neither of the retries or delay or retries are set, they will default to their respective defaults. +This allows for all items to be created, then checked that the task finishes successfully. +This also speeds up the overall role. + +|Variable Name|Default Value|Required|Description| +|`aap_configuration_async_retries`|30|no|This variable sets the number of retries to attempt for the role globally.| +|`controller_configuration_applications_async_retries`|`{{ aap_configuration_async_retries }}`|no|This variable sets the number of retries to attempt for the role.| +|`aap_configuration_async_delay`|1|no|This sets the delay between retries for the role globally.| +|`controller_configuration_applications_async_delay`|`aap_configuration_async_delay`|no|This sets the delay between retries for the role.| +|`aap_configuration_loop_delay`|0|no|This sets the pause between each item in the loop for the roles globally. To help when API is getting overloaded.| +|`controller_configuration_applications_loop_delay`|`aap_configuration_loop_delay`|no|This sets the pause between each item in the loop for the role. To help when API is getting overloaded.| +|`aap_configuration_async_dir`|`null`|no|Sets the directory to write the results file for async tasks. The default value is set to `null` which uses the Ansible Default of `/root/.ansible_async/`.| + +## Data Structure + +### Application Variables + +|Variable Name|Default Value|Required|Type|Description| +|`name`|""|yes|str|Name of application| +|`new_name`|""|no|str|Setting this option will change the existing name (looked up via the name field).| +|`organization`|""|yes|str|Name of the organization for the application| +|`description`|""|no|str|Description to use for the application.| +|`authorization_grant_type`|"password"|yes|str|Grant type for tokens in this application, "password" or "authorization-code"| +|`client_type`|"public"|yes|str|Application client type, "confidential" or "public"| +|`redirect_uris`|""|no|str|Allowed urls list, space separated. Required with "authorization-code" grant type| +|`skip_authorization`|"false"|yes|bool|Set True to skip authorization step for completely trusted applications.| +|`state`|`present`|no|str|Desired state of the application.| + +### Standard Application Data Structure + +#### Json Example + +```json + { + "aap_applications": [ + { + "name": "controller Config Default Application", + "description": "Generic application, which can be used for oauth tokens", + "organization": "Default", + "state": "present", + "client_type": "confidential", + "authorization_grant_type": "password" + } + ] +} +``` + +#### Yaml Example + +```yaml +aap_applications: + - name: "controller Config Default Application" + description: "Generic application, which can be used for oauth tokens" + organization: "Default" + state: "present" + client_type: "confidential" + authorization_grant_type: "password" +``` + +## Playbook Examples + +### Standard Role Usage + +```yaml +- name: Playbook to configure ansible controller post installation + hosts: localhost + connection: local + # Define following vars here, or in platform_configs/controller_auth.yml + # aap_hostname: ansible-controller-web-svc-test-project.example.com + # aap_username: admin + # aap_password: changeme + pre_tasks: + - name: Include vars from platform_configs directory + ansible.builtin.include_vars: + dir: ./yaml + ignore_files: [controller_config.yml.template] + extensions: ["yml"] + roles: + - {role: infra.aap_configuration.applications, when: aap_applications is defined} +``` + +## License + +[GPL-3.0](https://github.com/redhat-cop/aap_configuration#licensing) + +## Author + +[Mike Shriver](https://github.com/mshriver) diff --git a/collections/controller_configuration/controller_bulk_host_create.md b/collections/controller_configuration/controller_bulk_host_create.md new file mode 100644 index 0000000..df8e671 --- /dev/null +++ b/collections/controller_configuration/controller_bulk_host_create.md @@ -0,0 +1,143 @@ +--- +layout: default +title: controller_bulk_host_create +parent: infra.controller_configuration +--- + +# controller_configuration.bulk_host_create + +## Description + +An Ansible Role to create bulk hosts on Ansible Controller. + +## Requirements + +ansible-galaxy collection install -r tests/collections/requirements.yml to be installed +Currently: + awx.awx + or + ansible.controller + +## Variables + +|Variable Name|Default Value|Required|Description|Example| +|`aap_hostname`|""|yes|URL to the Ansible Controller Server.|127.0.0.1| +|`aap_validate_certs`|`True`|no|Whether or not to validate the Ansible Controller Server's SSL certificate.|| +|`aap_username`|""|no|Admin User on the Ansible Controller Server. Either username / password or oauthtoken need to be specified.|| +|`aap_password`|""|no|Controller Admin User's password on the Ansible Controller Server. This should be stored in an Ansible Vault at vars/controller-secrets.yml or elsewhere and called from a parent playbook. Either username / password or oauthtoken need to be specified.|| +|`controller_oauthtoken`|""|no|Controller Admin User's token on the Ansible Controller Server. This should be stored in an Ansible Vault at or elsewhere and called from a parent playbook. Either username / password or oauthtoken need to be specified.|| +|`controller_request_timeout`|`10`|no|Specify the timeout in seconds Ansible should use in requests to the Ansible Automation Platform host.|| +|`controller_configuration_bulk_hosts_secure_logging`|`see below`|yes|Data structure describing your organization or organizations Described below.|| + +### Secure Logging Variables + +The following Variables compliment each other. +If Both variables are not set, secure logging defaults to false. +The role defaults to False as normally the add ******* task does not include sensitive information. +controller_configuration_*******_secure_logging defaults to the value of aap_configuration_secure_logging if it is not explicitly called. This allows for secure logging to be toggled for the entire suite of controller configuration roles with a single variable, or for the user to selectively use it. + +|Variable Name|Default Value|Required|Description| +|`controller_configuration_bulk_hosts_secure_logging`|`False`|no|Whether or not to include the sensitive ******* role tasks in the log. Set this value to `True` if you will be providing your sensitive values from elsewhere.| +|`aap_configuration_secure_logging`|`False`|no|This variable enables secure logging as well, but is shared across multiple roles, see above.| + +### Asynchronous Retry Variables + +The following Variables set asynchronous retries for the role. +If neither of the retries or delay or retries are set, they will default to their respective defaults. +This allows for all items to be created, then checked that the task finishes successfully. +This also speeds up the overall role. + +|Variable Name|Default Value|Required|Description| +|`aap_configuration_async_retries`|30|no|This variable sets the number of retries to attempt for the role globally.| +|`controller_configuration_bulk_hosts_async_retries`|`{{ aap_configuration_async_retries }}`|no|This variable sets the number of retries to attempt for the role.| +|`aap_configuration_async_delay`|1|no|This sets the delay between retries for the role globally.| +|`controller_configuration_bulk_hosts_async_delay`|`aap_configuration_async_delay`|no|This sets the delay between retries for the role.| +|`aap_configuration_loop_delay`|0|no|This sets the pause between each item in the loop for the roles globally. To help when API is getting overloaded.| +|`controller_configuration_bulk_hosts_loop_delay`|`aap_configuration_loop_delay`|no|This sets the pause between each item in the loop for the role. To help when API is getting overloaded.| +|`aap_configuration_async_dir`|`null`|no|Sets the directory to write the results file for async tasks. The default value is set to `null` which uses the Ansible Default of `/root/.ansible_async/`.| + +## Data Structure + +### Bulk Host Variables + +|Variable Name|Default Value|Required|Type|Description| +|`hosts`|""|yes|list|List of hosts and host options to add to inventory. Documented below| +|`inventory`|""|yes|str|Inventory name or ID the hosts should be made a member of.| + +### Bulk Host Sub Options + +|Variable Name|Default Value|Required|Type|Description| +|`name`|""|no|list|The name to use for the host.| +|`description`|""|no|str|The description to use for the host.| +|`enabled`|""|no|bool|If the host should be enabled.| +|`variables`|""|no|dict|Variables to use for the host.| +|`instance`|""|no|list|instance to use for the host.| + +### Standard Bulk Host Data Structure + +#### Json Example + +```json +{ + "controller_bulk_hosts": [ + { + "inventory": "localhost", + "hosts": [ + { + "name": "localhost" + }, + { + "name": "127.0.0.1", + "variables": { + "some_var": "some_val", + "ansible_connection": "local" + } + } + ] + } + ] +} +``` + +#### Yaml Example + +```yaml +controller_bulk_hosts: + - inventory: localhost + hosts: + - name: localhost + - name: 127.0.0.1 + variables: + some_var: some_val + ansible_connection: local +``` + +## Playbook Examples + +### Standard Role Usage + +```yaml +- name: Playbook to configure ansible controller post installation + hosts: localhost + connection: local + # Define following vars here, or in platform_configs/controller_auth.yml + # aap_hostname: ansible-controller-web-svc-test-project.example.com + # aap_username: admin + # aap_password: changeme + pre_tasks: + - name: Include vars from platform_configs directory + include_vars: + dir: ./yaml + ignore_files: [controller_config.yml.template] + extensions: ["yml"] + roles: + - {role: redhat_cop.controller_configuration.bulk_host_create, when: controller_bulk_hosts is defined} +``` + +## License + +[GPL-3.0](https://github.com/redhat-cop/aap_configuration#licensing) + +## Author + +[Sean Sullivan](https://github.com/sean-m-sullivan) diff --git a/collections/controller_configuration/controller_bulk_job_launch.md b/collections/controller_configuration/controller_bulk_job_launch.md new file mode 100644 index 0000000..a517309 --- /dev/null +++ b/collections/controller_configuration/controller_bulk_job_launch.md @@ -0,0 +1,141 @@ +--- +layout: default +title: controller_bulk_job_launch +parent: infra.controller_configuration +--- + +# controller_configuration.bulk_job_launch + +## Description + +An Ansible Role to launch bulk jobs on Ansible Controller. + +## Requirements + +ansible-galaxy collection install -r tests/collections/requirements.yml to be installed +Currently: + awx.awx + or + ansible.controller + +## Variables + +|Variable Name|Default Value|Required|Description|Example| +|`platform_state`|"present"|no|The state all objects will take unless overridden by object default|'absent'| +|`aap_hostname`|""|yes|URL to the Ansible Automation Platform Server.|127.0.0.1| +|`aap_validate_certs`|`True`|no|Whether or not to validate the Ansible Automation Platform Server's SSL certificate.|| +|`aap_username`|""|no|Admin User on the Ansible Automation Platform Server. Either username / password or oauthtoken need to be specified.|| +|`aap_password`|""|no|Platform Admin User's password on the Server. This should be stored in an Ansible Vault at vars/platform-secrets.yml or elsewhere and called from a parent playbook.|| +|`aap_token`|""|no|Controller Admin User's token on the Ansible Automation Platform Server. This should be stored in an Ansible Vault at or elsewhere and called from a parent playbook. Either username / password or oauthtoken need to be specified.|| +|`aap_request_timeout`|`10`|no|Specify the timeout in seconds Ansible should use in requests to the Ansible Automation Platform host.|| +|`controller_bulk_launch_jobs`|`see below`|yes|Data structure describing your organization or organizations Described below.|| + +### Secure Logging Variables + +The following Variables compliment each other. +If Both variables are not set, secure logging defaults to false. +The role defaults to False as normally the add ******* task does not include sensitive information. +controller_configuration_*******_secure_logging defaults to the value of aap_configuration_secure_logging if it is not explicitly called. This allows for secure logging to be toggled for the entire suite of controller configuration roles with a single variable, or for the user to selectively use it. + +|Variable Name|Default Value|Required|Description| +|`controller_configuration_bulk_job_launch_secure_logging`|`False`|no|Whether or not to include the sensitive bulk_job_launch role tasks in the log. Set this value to `True` if you will be providing your sensitive values from elsewhere.| +|`aap_configuration_secure_logging`|`False`|no|This variable enables secure logging as well, but is shared across multiple roles, see above.| + +### Asynchronous Retry Variables + +The following Variables set asynchronous retries for the role. +If neither of the retries or delay or retries are set, they will default to their respective defaults. +This allows for all items to be created, then checked that the task finishes successfully. +This also speeds up the overall role. + +|Variable Name|Default Value|Required|Description| +|`aap_configuration_async_retries`|30|no|This variable sets the number of retries to attempt for the role globally.| +|`controller_configuration_bulk_job_launch_async_retries`|`{{ aap_configuration_async_retries }}`|no|This variable sets the number of retries to attempt for the role.| +|`aap_configuration_async_delay`|1|no|This sets the delay between retries for the role globally.| +|`controller_configuration_bulk_job_launch_async_delay`|`aap_configuration_async_delay`|no|This sets the delay between retries for the role.| +|`aap_configuration_loop_delay`|0|no|This sets the pause between each item in the loop for the roles globally. To help when API is getting overloaded.| +|`controller_configuration_bulk_job_launch_loop_delay`|`aap_configuration_loop_delay`|no|This sets the pause between each item in the loop for the role. To help when API is getting overloaded.| + +## Data Structure + +### Bulk Host Variables + +|Variable Name|Default Value|Required|Type|Description| +|`jobs`|""|yes|list|List of jobs and job options to launch. Documented below| +|`description`|""|no|str|Optional description of this bulk job.| +|`organization`|""|no|str|Organization for the bulk job. Affects who can see the resulting bulk job. If not provided, will use the organization the user is in.| +|`inventory`|""|no|str|Inventory to use for the job, only used if prompt for inventory is set.| +|`scm_branch`|""|no|str|A specific of the SCM project to run the template on.| +|`extra_vars`|""|no|dict|extra_vars to use for the Job Template. ask_extra_vars needs to be set to True via controller_job_template module.| +|`limit`|""|no|str|Limit to use for the job_template.| +|`job_tags`|""|no|str|Specific tags to use for from playbook.| +|`skip_tags`|""|no|str|Specific tags to skip from the playbook.| +|`wait`|""|no|bool|Wait for the job to complete.| +|`interval`|2|no|float|The interval to request an update from controller.| + +### Bulk Job Launch Sub Options + +|Variable Name|Default Value|Required|Type|Description| +|`unified_job_template`|""|yes|int|The ID of object that is to be launched. Example objects include projects, inventory sources, and templates. Required if state='present.| +|`inventory`|""|no|str|Inventory to use for the job, only used if prompt for inventory is set.| +|`execution_environment`|Job Template default|no|str|Execution Environment applied as a prompt. Job Template default used if not set. Only allowed if `ask_execution_environment_on_launch` set to true on Job Template| +|`instance_groups`|Job Template default|no|str| List of Instance Groups applied as a prompt. Job Template default used if not set. Only allowed if `ask_instance_groups_on_launch` set to true on Job Template| +|`credentials`|""|no|list|TCredential to use for job, only used if prompt for credential is set.| +|`labels`|Job Template default|no|list|List of labels to use in the job run. Job Template default used if not set. Only allowed if `ask_labels_on_launch` set to true on Job Template| +|`extra_data`|""|no|dict|extra_data to use for the Job Template. ask_extra_vars needs to be set to True via controller_job_template module.| +|`diff_mode`|""|no|bool|Show the changes made by Ansible tasks where supported.| +|`verbosity`|""|no|int|Verbosity level for this job run.| +|`scm_branch`|""|no|str|A specific of the SCM project to run the template on.| +|`job_type`|""|no|str|Job_type to use for the job, only used if prompt for job_type is set. Run or Check are the options.| +|`job_tags`|""|no|str|Specific tags to use for from playbook.| +|`skip_tags`|""|no|str|Specific tags to skip from the playbook.| +|`limit`|""|no|str|Limit to use for the job_template.| +|`forks`|Job Template default|no|int|Forks applied as a prompt. Job Template default used if not set. Only allowed if `ask_forks_on_launch` set to true on Job Template| +|`job_slice_count`|Job Template default|no|int|Job Slice Count to use in the job run. Job Template default used if not set. Only allowed if `ask_job_slice_count_on_launch` set to true on Job Template| +|`identifier`|""|yes|str|An identifier for the resulting workflow node that represents this job that is unique within its workflow. It is copied to workflow job nodes corresponding to this node. This functions the same as the name field for other resources, however if it is not set, it will be set to a random UUID4 value.| +|`timeout`|""|no|int|If waiting for the job to complete this will abort after this amount of seconds.| + +### Standard Bulk Job Launch Data Structure + +#### Json Example + +```json +{ +} + +``` + +#### Yaml Example + +```yaml +``` + +## Playbook Examples + +### Standard Role Usage + +```yaml +- name: Playbook to configure ansible controller post installation + hosts: localhost + connection: local + # Define following vars here, or in platform_configs/controller_auth.yml + # aap_hostname: ansible-controller-web-svc-test-project.example.com + # aap_username: admin + # aap_password: changeme + pre_tasks: + - name: Include vars from platform_configs directory + include_vars: + dir: ./yaml + ignore_files: [controller_config.yml.template] + extensions: ["yml"] + roles: + - {role: redhat_cop.controller_configuration.license, when: controller_license is defined} +``` + +## License + +[GPL-3.0](https://github.com/redhat-cop/aap_configuration#licensing) + +## Author + +[Sean Sullivan](https://github.com/sean-m-sullivan) diff --git a/collections/controller_configuration/controller_credential_input_sources.md b/collections/controller_configuration/controller_credential_input_sources.md new file mode 100644 index 0000000..9724687 --- /dev/null +++ b/collections/controller_configuration/controller_credential_input_sources.md @@ -0,0 +1,174 @@ +--- +layout: default +title: controller_credential_input_sources +parent: infra.controller_configuration +--- + +# controller_configuration.credential_input_sources + +## Description + +An Ansible Role to create/update/remove credential input sources on Ansible Controller, the below example is for CyberArk as an input source, change accordingly to match your input source type. + +## Requirements + +ansible-galaxy collection install -r tests/collections/requirements.yml to be installed +Currently: + awx.awx + or + ansible.controller + +## Variables + +|Variable Name|Default Value|Required|Description|Example| +|`platform_state`|"present"|no|The state all objects will take unless overridden by object default|'absent'| +|`aap_hostname`|""|yes|URL to the Ansible Automation Platform Server.|127.0.0.1| +|`aap_validate_certs`|`True`|no|Whether or not to validate the Ansible Automation Platform Server's SSL certificate.|| +|`aap_username`|""|no|Admin User on the Ansible Automation Platform Server. Either username / password or oauthtoken need to be specified.|| +|`aap_password`|""|no|Platform Admin User's password on the Server. This should be stored in an Ansible Vault at vars/platform-secrets.yml or elsewhere and called from a parent playbook.|| +|`aap_token`|""|no|Controller Admin User's token on the Ansible Automation Platform Server. This should be stored in an Ansible Vault at or elsewhere and called from a parent playbook. Either username / password or oauthtoken need to be specified.|| +|`aap_request_timeout`|`10`|no|Specify the timeout in seconds Ansible should use in requests to the Ansible Automation Platform host.|| +|`controller_credential_input_sources`|`see below`|yes|Data structure describing your credential input sources Described below.|| + +### Enforcing defaults + +The following Variables compliment each other. +If Both variables are not set, enforcing default values is not done. +Enabling these variables enforce default values on options that are optional in the controller API. +This should be enabled to enforce configuration and prevent configuration drift. It is recomended to be enabled, however it is not enforced by default. + +Enabling this will enforce configurtion without specifying every option in the configuration files. + +'controller_configuration_credential_input_sources_enforce_defaults' defaults to the value of 'aap_configuration_enforce_defaults' if it is not explicitly called. This allows for enforced defaults to be toggled for the entire suite of controller configuration roles with a single variable, or for the user to selectively use it. + +|Variable Name|Default Value|Required|Description| +|`controller_configuration_credential_input_sources_enforce_defaults`|`False`|no|Whether or not to enforce default option values on only the applications role| +|`aap_configuration_enforce_defaults`|`False`|no|This variable enables enforced default values as well, but is shared across multiple roles, see above.| + +### Secure Logging Variables + +The following Variables compliment each other. +If Both variables are not set, secure logging defaults to false. +The role defaults to False as normally the add credential input source task does not include sensitive information. +controller_configuration_credential_input_sources_secure_logging defaults to the value of aap_configuration_secure_logging if it is not explicitly called. This allows for secure logging to be toggled for the entire suite of controller configuration roles with a single variable, or for the user to selectively use it. + +|Variable Name|Default Value|Required|Description| +|`controller_configuration_credential_input_sources_secure_logging`|`False`|no|Whether or not to include the sensitive credential_input_source role tasks in the log. Set this value to `True` if you will be providing your sensitive values from elsewhere.| +|`aap_configuration_secure_logging`|`False`|no|This variable enables secure logging as well, but is shared across multiple roles, see above.| + +### Asynchronous Retry Variables + +The following Variables set asynchronous retries for the role. +If neither of the retries or delay or retries are set, they will default to their respective defaults. +This allows for all items to be created, then checked that the task finishes successfully. +This also speeds up the overall role. + +|Variable Name|Default Value|Required|Description| +|`aap_configuration_async_retries`|30|no|This variable sets the number of retries to attempt for the role globally.| +|`controller_configuration_credential_input_sources_async_retries`|`{{ aap_configuration_async_retries }}`|no|This variable sets the number of retries to attempt for the role.| +|`aap_configuration_async_delay`|1|no|This sets the delay between retries for the role globally.| +|`controller_configuration_credential_input_sources_async_delay`|`aap_configuration_async_delay`|no|This sets the delay between retries for the role.| +|`aap_configuration_loop_delay`|0|no|This sets the pause between each item in the loop for the roles globally. To help when API is getting overloaded.| +|`controller_configuration_credential_input_sources_loop_delay`|`aap_configuration_loop_delay`|no|This sets the pause between each item in the loop for the role. To help when API is getting overloaded.| +|`aap_configuration_async_dir`|`null`|no|Sets the directory to write the results file for async tasks. The default value is set to `null` which uses the Ansible Default of `/root/.ansible_async/`.| + +## Data Structure + +### Credential Input Source Variables + +|Variable Name|Default Value|Required|Type|Description| +|`target_credential`|""|yes|str|Name of credential to have the input source applied| +|`input_field_name`|""|yes|str|Name of field which will be written by the input source| +|`source_credential`|""|no|str|Name of the source credential which points to an external secret lookup credential | +|`metadata`|""|no|dict|The metadata applied to the source.| +|`description`|""|no|str|Description to use for the credential input source.| +|`state`|`present`|no|str|Desired state of the resource.| + +For further details on fields see . The input accepted by the `metadata` field will differ depending on the credential plugin being used. + +### Standard Credential Input Source Data Structure + +#### Json Example + +```json +{ + "controller_credential_input_sources": [ + { + "source_credential": "cyberark", + "target_credential": "gitlab", + "input_field_name": "password", + "metadata": { + "object_query": "Safe=MY_SAFE;Object=AWX-user", + "object_query_format": "Exact" + }, + "description": "Fill the gitlab credential from CyberArk" + }, + { + "source_credential": "hashivault", + "target_credential": "gitlab", + "input_field_name": "password", + "metadata": { + "secret_backend": "mykv", + "secret_path": "vault/path/to/gitlab/secret", + "auth_path": "approle", + "secret_key": "GITLAB_PASSWORD_FROM_HASHI_VAULT", + "secret_version": "v2" + }, + "description": "Fill the gitlab credential from HashiCorp Vault" + } + ] +} +``` + +#### Yaml Example + +```yaml +controller_credential_input_sources: + - source_credential: hashivault + target_credential: gitlab + input_field_name: password + metadata: + secret_backend: mykv + secret_path: vault/path/to/gitlab/secret + auth_path: approle + secret_key: GITLAB_PASSWORD_FROM_HASHI_VAULT + secret_version + description: Fill the gitlab credential from HashiCorp Vault + - source_credential: cyberark + target_credential: gitlab + input_field_name: password + metadata: + object_query: "Safe=MY_SAFE;Object=AWX-user" + object_query_format: "Exact" + description: Fill the gitlab credential from CyberArk +``` + +## Playbook Examples + +### Standard Role Usage + +```yaml +- name: Playbook to configure ansible controller post installation + hosts: localhost + connection: local + # Define following vars here, or in platform_configs/controller_auth.yml + # aap_hostname: ansible-controller-web-svc-test-project.example.com + # aap_username: admin + # aap_password: changeme + pre_tasks: + - name: Include vars from platform_configs directory + ansible.builtin.include_vars: + dir: ./yaml + ignore_files: [controller_config.yml.template] + extensions: ["yml"] + roles: + - {role: infra.aap_configuration.credential_input_sources, when: controller_credential_input_sources is defined} +``` + +## License + +[GPL-3.0](https://github.com/redhat-cop/aap_configuration#licensing) + +## Author + +[Tom Page](https://github.com/Tompage1994) diff --git a/collections/controller_configuration/controller_credential_types.md b/collections/controller_configuration/controller_credential_types.md new file mode 100644 index 0000000..c055840 --- /dev/null +++ b/collections/controller_configuration/controller_credential_types.md @@ -0,0 +1,250 @@ +--- +layout: default +title: controller_credential_types +parent: infra.controller_configuration +--- + +# controller_configuration.credential_types + +## Description + +An Ansible Role to create/update/remove Credential Types on Ansible Controller. + +## Requirements + +ansible-galaxy collection install -r tests/collections/requirements.yml to be installed +Currently: + awx.awx + or + ansible.controller + +## Variables + +|Variable Name|Default Value|Required|Description|Example| +|`platform_state`|"present"|no|The state all objects will take unless overridden by object default|'absent'| +|`aap_hostname`|""|yes|URL to the Ansible Automation Platform Server.|127.0.0.1| +|`aap_validate_certs`|`True`|no|Whether or not to validate the Ansible Automation Platform Server's SSL certificate.|| +|`aap_username`|""|no|Admin User on the Ansible Automation Platform Server. Either username / password or oauthtoken need to be specified.|| +|`aap_password`|""|no|Platform Admin User's password on the Server. This should be stored in an Ansible Vault at vars/platform-secrets.yml or elsewhere and called from a parent playbook.|| +|`aap_token`|""|no|Controller Admin User's token on the Ansible Automation Platform Server. This should be stored in an Ansible Vault at or elsewhere and called from a parent playbook. Either username / password or oauthtoken need to be specified.|| +|`aap_request_timeout`|`10`|no|Specify the timeout in seconds Ansible should use in requests to the Ansible Automation Platform host.|| +|`controller_credential_types`|`see below`|yes|Data structure describing your credential types Described below. Alias: credential_types || + +### Enforcing defaults + +The following Variables compliment each other. +If Both variables are not set, enforcing default values is not done. +Enabling these variables enforce default values on options that are optional in the controller API. +This should be enabled to enforce configuration and prevent configuration drift. It is recomended to be enabled, however it is not enforced by default. + +Enabling this will enforce configurtion without specifying every option in the configuration files. + +'controller_configuration_credential_types_enforce_defaults' defaults to the value of 'aap_configuration_enforce_defaults' if it is not explicitly called. This allows for enforced defaults to be toggled for the entire suite of controller configuration roles with a single variable, or for the user to selectively use it. + +|Variable Name|Default Value|Required|Description| +|`controller_configuration_credential_types_enforce_defaults`|`False`|no|Whether or not to enforce default option values on only the applications role| +|`aap_configuration_enforce_defaults`|`False`|no|This variable enables enforced default values as well, but is shared across multiple roles, see above.| + +### Secure Logging Variables + +The following Variables compliment each other. +If Both variables are not set, secure logging defaults to false. +The role defaults to False as normally the add credential type task does not include sensitive information. +controller_configuration_credential_types_secure_logging defaults to the value of aap_configuration_secure_logging if it is not explicitly called. This allows for secure logging to be toggled for the entire suite of configuration roles with a single variable, or for the user to selectively use it. + +|Variable Name|Default Value|Required|Description| +|`controller_configuration_credential_types_secure_logging`|`False`|no|Whether or not to include the sensitive Credential Type role tasks in the log. Set this value to `True` if you will be providing your sensitive values from elsewhere.| +|`aap_configuration_secure_logging`|`False`|no|This variable enables secure logging as well, but is shared across multiple roles, see above.| + +### Asynchronous Retry Variables + +The following Variables set asynchronous retries for the role. +If neither of the retries or delay or retries are set, they will default to their respective defaults. +This allows for all items to be created, then checked that the task finishes successfully. +This also speeds up the overall role. + +|Variable Name|Default Value|Required|Description| +|`aap_configuration_async_retries`|30|no|This variable sets the number of retries to attempt for the role globally.| +|`controller_configuration_credential_types_async_retries`|`aap_configuration_async_retries`|no|This variable sets the number of retries to attempt for the role.| +|`aap_configuration_async_delay`|1|no|This sets the delay between retries for the role globally.| +|`controller_configuration_credential_types_async_delay`|`aap_configuration_async_delay`|no|This sets the delay between retries for the role.| +|`aap_configuration_loop_delay`|0|no|This sets the pause between each item in the loop for the roles globally. To help when API is getting overloaded.| +|`controller_configuration_credential_types_loop_delay`|`aap_configuration_loop_delay`|no|This sets the pause between each item in the loop for the role. To help when API is getting overloaded.| +|`aap_configuration_async_dir`|`null`|no|Sets the directory to write the results file for async tasks. The default value is set to `null` which uses the Ansible Default of `/root/.ansible_async/`.| + +## Data Structure + +### Credential Type Variables + +|Variable Name|Default Value|Required|Description| +|`name`|""|yes|Name of Credential Type| +|`new_name`|""|no|Setting this option will change the existing name (looked up via the name field).| +|`description`|`False`|no|The description of the credential type to give more detail about it.| +|`injectors`|""|no|Enter injectors using either JSON or YAML syntax. Refer to the Ansible controller documentation for example syntax. See below on proper formatting.| +|`inputs`|""|no|Enter inputs using either JSON or YAML syntax. Refer to the Ansible controller documentation for example syntax.| +|`kind`|"cloud"|no|The type of credential type being added. Note that only cloud and net can be used for creating credential types.| +|`state`|`present`|no|Desired state of the resource.| + +### Formating Injectors + +Injectors use a standard Jinja templating format to describe the resource. + +Example: + +```json +{{ variable }} +``` + +Because of this it is difficult to provide controller with the required format for these fields. + +The workaround is easier to do in yaml with unsafe syntax, to read more about this check out the [documentation](https://docs.ansible.com/ansible/latest/user_guide/playbooks_advanced_syntax.html): + +```yaml +!unsafe '{{ variable }}' +``` + +If you want to use json you will have to use the following format: + +```json +{ { variable }} +``` + +The role will strip the double space between the curly bracket in order to provide controller with the correct format for the Injectors. + +### Input and Injector Schema + +The following details the data format to use for inputs and injectors. These can be in either YAML or JSON For the most up to date information and more details see [Custom Credential Types - Ansible Controller Documentation](https://docs.ansible.com/automation-controller/latest/html/userguide/credential_plugins.html) + +#### Input Schema + +```yaml +fields: + - type: string + id: username + label: Username + - type: string + id: password + label: Password + secret: true +required: + - username + - password +``` + +#### Injector Schema + +```json +{ + "file": { + "template": "[mycloud]\ntoken={{ api_token }}" + }, + "env": { + "THIRD_PARTY_CLOUD_API_TOKEN": "{{ api_token }}" + }, + "extra_vars": { + "some_extra_var": "{{ username }}:{{ password }}" + } +} +``` + +### Standard Credential Type Data Structure + +#### Json Example + +```json +{ + "controller_credential_types": [ + { + "name": "REST API Credential", + "description": "REST API Credential", + "kind": "cloud", + "inputs": { + "fields": [ + { + "type": "string", + "id": "rest_username", + "label": "REST Username" + }, + { + "secret": true, + "type": "string", + "id": "rest_password", + "label": "REST Password" + } + ], + "required": [ + "rest_username", + "rest_password" + ] + }, + "injectors": { + "extra_vars": { + "rest_password": "{ { rest_password }}", + "rest_username": "{ { rest_username }}" + }, + "env": { + "rest_username_env": "{ { rest_username }}", + "rest_password_env": "{ { rest_password }}" + } + } + } + ] +} +``` + +#### Yaml Example + +```yaml +controller_credential_types: +- name: REST API Credential + description: REST API Credential + inputs: + fields: + - type: string + id: rest_username + label: REST Username + - secret: true + type: string + id: rest_password + label: REST Password + required: + - rest_username + - rest_password + injectors: + extra_vars: + rest_password: !unsafe "{{ rest_password }}" + rest_username: !unsafe "{{ rest_username }}" + env: + rest_username_env: !unsafe "{{ rest_username }}" + rest_password_env: !unsafe "{{ rest_password }}" +``` + +## Playbook Examples + +### Standard Role Usage + +```yaml +- name: Playbook to configure ansible controller post installation + hosts: localhost + connection: local + # Define following vars here, or in platform_configs/controller_auth.yml + # aap_hostname: ansible-controller-web-svc-test-project.example.com + # aap_username: admin + # aap_password: changeme + pre_tasks: + - name: Include vars from platform_configs directory + ansible.builtin.include_vars: + dir: ./yaml + ignore_files: [controller_config.yml.template] + extensions: ["yml"] + roles: + - {role: infra.aap_configuration.credential_types, when: controller_credential_types is defined} +``` + +## License + +[GPL-3.0](https://github.com/redhat-cop/aap_configuration#licensing) + +## Author + +[Sean Sullivan](https://github.com/sean-m-sullivan) diff --git a/collections/controller_configuration/controller_credentials.md b/collections/controller_configuration/controller_credentials.md new file mode 100644 index 0000000..a817e6e --- /dev/null +++ b/collections/controller_configuration/controller_credentials.md @@ -0,0 +1,176 @@ +--- +layout: default +title: controller_credentials +parent: infra.controller_configuration +--- + +# controller_configuration.credentials + +## Description + +An Ansible Role to create/update/remove Credentials on Ansible Controller. + +## Requirements + +ansible-galaxy collection install -r tests/collections/requirements.yml to be installed +Currently: + awx.awx + or + ansible.controller + +## Variables + +|Variable Name|Default Value|Required|Description|Example| +|`platform_state`|"present"|no|The state all objects will take unless overridden by object default|'absent'| +|`aap_hostname`|""|yes|URL to the Ansible Automation Platform Server.|127.0.0.1| +|`aap_validate_certs`|`True`|no|Whether or not to validate the Ansible Automation Platform Server's SSL certificate.|| +|`aap_username`|""|no|Admin User on the Ansible Automation Platform Server. Either username / password or oauthtoken need to be specified.|| +|`aap_password`|""|no|Platform Admin User's password on the Server. This should be stored in an Ansible Vault at vars/platform-secrets.yml or elsewhere and called from a parent playbook.|| +|`aap_token`|""|no|Controller Admin User's token on the Ansible Automation Platform Server. This should be stored in an Ansible Vault at or elsewhere and called from a parent playbook. Either username / password or oauthtoken need to be specified.|| +|`aap_request_timeout`|`10`|no|Specify the timeout in seconds Ansible should use in requests to the Ansible Automation Platform host.|| +|`controller_credentials`|`see below`|yes|Data structure describing your credentials Described below. Alias: credentials || + +### Enforcing defaults + +The following Variables compliment each other. +If Both variables are not set, enforcing default values is not done. +Enabling these variables enforce default values on options that are optional in the controller API. +This should be enabled to enforce configuration and prevent configuration drift. It is recomended to be enabled, however it is not enforced by default. + +Enabling this will enforce configurtion without specifying every option in the configuration files. + +'controller_configuration_credentials_enforce_defaults' defaults to the value of 'aap_configuration_enforce_defaults' if it is not explicitly called. This allows for enforced defaults to be toggled for the entire suite of controller configuration roles with a single variable, or for the user to selectively use it. + +|Variable Name|Default Value|Required|Description| +|`controller_configuration_credentials_enforce_defaults`|`False`|no|Whether or not to enforce default option values on only the applications role| +|`aap_configuration_enforce_defaults`|`False`|no|This variable enables enforced default values as well, but is shared across multiple roles, see above.| + +### Secure Logging Variables + +The following Variables compliment each other. +If Both variables are not set, secure logging defaults to false. +The role defaults to False as normally the add credentials task does not include sensitive information. +controller_configuration_credentials_secure_logging defaults to the value of aap_configuration_secure_logging if it is not explicitly called. This allows for secure logging to be toggled for the entire suite of configuration roles with a single variable, or for the user to selectively use it. + +|Variable Name|Default Value|Required|Description| +|`controller_configuration_credentials_secure_logging`|`False`|no|Whether or not to include the sensitive Credential role tasks in the log. Set this value to `True` if you will be providing your sensitive values from elsewhere.| +|`aap_configuration_secure_logging`|`False`|no|This variable enables secure logging as well, but is shared across multiple roles, see above.| + +### Asynchronous Retry Variables + +The following Variables set asynchronous retries for the role. +If neither of the retries or delay or retries are set, they will default to their respective defaults. +This allows for all items to be created, then checked that the task finishes successfully. +This also speeds up the overall role. + +|Variable Name|Default Value|Required|Description| +|`aap_configuration_async_retries`|30|no|This variable sets the number of retries to attempt for the role globally.| +|`controller_configuration_credentials_async_retries`|`{{ aap_configuration_async_retries }}`|no|This variable sets the number of retries to attempt for the role.| +|`aap_configuration_async_delay`|1|no|This sets the delay between retries for the role globally.| +|`controller_configuration_credentials_async_delay`|`aap_configuration_async_delay`|no|This sets the delay between retries for the role.| +|`aap_configuration_loop_delay`|0|no|This sets the pause between each item in the loop for the roles globally. To help when API is getting overloaded.| +|`controller_configuration_credentials_loop_delay`|`aap_configuration_loop_delay`|no|This sets the pause between each item in the loop for the role. To help when API is getting overloaded.| +|`aap_configuration_async_dir`|`null`|no|Sets the directory to write the results file for async tasks. The default value is set to `null` which uses the Ansible Default of `/root/.ansible_async/`.| + +## Data Structure + +### Credential Variables + +|Variable Name|Default Value|Required|Description| +|`name`|""|yes|Name of Credential| +|`new_name`|""|no|Setting this option will change the existing name (looked up via the name field).| +|`copy_from`|""|no|Name or id to copy the credential from. This will copy an existing credential and change any parameters supplied.| +|`description`|`False`|no|Description of of Credential.| +|`organization`|""|no|Organization this Credential belongs to. If provided on creation, do not give either user or team.| +|`credential_type`|""|no|Name of credential type. See below for list of options. More information in Ansible controller documentation. | +|`inputs`|""|no|Credential inputs where the keys are var names used in templating. Refer to the Ansible controller documentation for example syntax. Individual examples can be found at /api/v2/credential_types/ on an controller.| +|`user`|""|no|User that should own this credential. If provided, do not give either team or organization. | +|`team`|""|no|Team that should own this credential. If provided, do not give either user or organization. | +|`state`|`present`|no|Desired state of the resource.| +|`update_secrets`|true|no| True will always change password if user specifies password, even if API gives $encrypted$ for password. False will only set the password if other values change too.| + +### Credential types + +To get a list of all the available builtin credential types, checkout the ansible doc's link [here](https://docs.ansible.com/automation-controller/latest/html/userguide/credentials.html#credential-types) + +### Standard Credential Data Structure + +#### Json Example + +```json + +{ + "controller_credentials": [ + { + "name": "gitlab", + "description": "Credentials for GitLab", + "organization": "Default", + "credential_type": "Source Control", + "inputs": { + "username": "person", + "password": "password" + } + } + ] +} +``` + +#### Yaml Example + +```yaml +controller_credentials: +- name: gitlab + description: Credentials for GitLab + organization: Default + credential_type: Source Control + inputs: + username: person + password: password +- name: hashivault + description: HashiCorp Vault Secret Lookup example using token auth + organization: Default + credential_type: HashiCorp Vault Secret Lookup + inputs: + url: https://vault.example.com:8243 + token: token + cacert: "{{ lookup('ansible.builtin.file', '/path/to/ca-certificates.crt') }}" + api_version: v2 +- name: localuser + description: Machine Credential example with become_method input + credential_type: Machine + inputs: + username: localuser + password: password + become_method: sudo +``` + +## Playbook Examples + +### Standard Role Usage + +```yaml +- name: Playbook to configure ansible controller post installation + hosts: localhost + connection: local + # Define following vars here, or in platform_configs/controller_auth.yml + # aap_hostname: ansible-controller-web-svc-test-project.example.com + # aap_username: admin + # aap_password: changeme + pre_tasks: + - name: Include vars from platform_configs directory + ansible.builtin.include_vars: + dir: ./yaml + ignore_files: [controller_config.yml.template] + extensions: ["yml"] + roles: + - {role: infra.aap_configuration.credentials, when: controller_credentials is defined} +``` + +## License + +[GPL-3.0](https://github.com/redhat-cop/aap_configuration#licensing) + +## Author + +[Andrew J. Huffman](https://github.com/ahuffman) +[Sean Sullivan](https://github.com/sean-m-sullivan) diff --git a/collections/controller_configuration/controller_execution_environments.md b/collections/controller_configuration/controller_execution_environments.md new file mode 100644 index 0000000..e5dd751 --- /dev/null +++ b/collections/controller_configuration/controller_execution_environments.md @@ -0,0 +1,138 @@ +--- +layout: default +title: controller_execution_environments +parent: infra.controller_configuration +--- + +# controller_configuration.execution_environments + +## Description + +An Ansible Role to create/update/remove execution_environments on Ansible Controller. + +## Requirements + +ansible-galaxy collection install -r tests/collections/requirements.yml to be installed +Currently: + awx.awx + or + ansible.controller + +## Variables + +|Variable Name|Default Value|Required|Description|Example| +|`platform_state`|"present"|no|The state all objects will take unless overridden by object default|'absent'| +|`aap_hostname`|""|yes|URL to the Ansible Automation Platform Server.|127.0.0.1| +|`aap_validate_certs`|`True`|no|Whether or not to validate the Ansible Automation Platform Server's SSL certificate.|| +|`aap_username`|""|no|Admin User on the Ansible Automation Platform Server. Either username / password or oauthtoken need to be specified.|| +|`aap_password`|""|no|Platform Admin User's password on the Server. This should be stored in an Ansible Vault at vars/platform-secrets.yml or elsewhere and called from a parent playbook.|| +|`aap_token`|""|no|Controller Admin User's token on the Ansible Automation Platform Server. This should be stored in an Ansible Vault at or elsewhere and called from a parent playbook. Either username / password or oauthtoken need to be specified.|| +|`aap_request_timeout`|`10`|no|Specify the timeout in seconds Ansible should use in requests to the Ansible Automation Platform host.|| +|`controller_execution_environments`|`see below`|yes|Data structure describing your organization or organizations Described below. Alias: execution_environments || + +### Enforcing defaults + +The following Variables compliment each other. +If Both variables are not set, enforcing default values is not done. +Enabling these variables enforce default values on options that are optional in the controller API. +This should be enabled to enforce configuration and prevent configuration drift. It is recomended to be enabled, however it is not enforced by default. + +Enabling this will enforce configurtion without specifying every option in the configuration files. + +'controller_configuration_execution_environments_enforce_defaults' defaults to the value of 'aap_configuration_enforce_defaults' if it is not explicitly called. This allows for enforced defaults to be toggled for the entire suite of controller configuration roles with a single variable, or for the user to selectively use it. + +|Variable Name|Default Value|Required|Description| +|`controller_configuration_execution_environments_enforce_defaults`|`False`|no|Whether or not to enforce default option values on only the applications role| +|`aap_configuration_enforce_defaults`|`False`|no|This variable enables enforced default values as well, but is shared across multiple roles, see above.| + +### Secure Logging Variables + +The following Variables compliment each other. +If Both variables are not set, secure logging defaults to false. +The role defaults to False as normally the add execution_environments task does not include sensitive information. +controller_configuration_execution_environments_secure_logging defaults to the value of aap_configuration_secure_logging if it is not explicitly called. This allows for secure logging to be toggled for the entire suite of controller configuration roles with a single variable, or for the user to selectively use it. + +|Variable Name|Default Value|Required|Description| +|`controller_configuration_execution_environments_secure_logging`|`False`|no|Whether or not to include the sensitive execution_environments role tasks in the log. Set this value to `True` if you will be providing your sensitive values from elsewhere.| +|`aap_configuration_secure_logging`|`False`|no|This variable enables secure logging as well, but is shared across multiple roles, see above.| + +### Asynchronous Retry Variables + +The following Variables set asynchronous retries for the role. +If neither of the retries or delay or retries are set, they will default to their respective defaults. +This allows for all items to be created, then checked that the task finishes successfully. +This also speeds up the overall role. + +|Variable Name|Default Value|Required|Description| +|`aap_configuration_async_retries`|30|no|This variable sets the number of retries to attempt for the role globally.| +|`controller_configuration_execution_environments_async_retries`|`{{ aap_configuration_async_retries }}`|no|This variable sets the number of retries to attempt for the role.| +|`aap_configuration_async_delay`|1|no|This sets the delay between retries for the role globally.| +|`controller_configuration_execution_environments_async_delay`|`aap_configuration_async_delay`|no|This sets the delay between retries for the role.| +|`aap_configuration_loop_delay`|0|no|This sets the pause between each item in the loop for the roles globally. To help when API is getting overloaded.| +|`controller_configuration_execution_environments_loop_delay`|`aap_configuration_loop_delay`|no|This sets the pause between each item in the loop for the role. To help when API is getting overloaded.| +|`aap_configuration_async_dir`|`null`|no|Sets the directory to write the results file for async tasks. The default value is set to `null` which uses the Ansible Default of `/root/.ansible_async/`.| + +## Data Structure + +### Execution Environment Variables + +|Variable Name|Default Value|Required|Type|Description| +|`name`|""|yes|str|Name of execution environment| +|`new_name`|""|no|str|Setting this option will change the existing name (looked up via the name field).| +|`description`|""|no|str|Description to use for the execution environment.| +|`image`|""|yes|str|Container image to use for the execution environment| +|`organization`|""|no|str|The organization the execution environment belongs to.| +|`credential`|""|no|str|Name of the credential to use for the execution environment.| +|`pull`|"missing"|no|choice("always", "missing", "never")|Determine image pull behavior| +|`state`|`present`|no|str|Desired state of the resource.| + +### Standard Execution Environment Data Structure + +#### Json Example + +```json +{ + "controller_execution_environments": [ + { + "name": "My EE", + "image": "quay.io/ansible/awx-ee" + } + ] +} +``` + +#### Yaml Example + +```yaml +controller_execution_environments: + - name: "My EE" + image: quay.io/ansible/awx-ee +``` + +## Playbook Examples + +### Standard Role Usage + +```yaml +- name: Add Execution Environments to controller + hosts: localhost + connection: local + gather_facts: false + vars: + controller_execution_environments: + name: "My EE" + image: quay.io/ansible/awx-ee + + tasks: + - name: Add Execution Environments + include_role: + name: infra.aap_configuration.execution_environments +``` + +## License + +[GPL-3.0](https://github.com/redhat-cop/aap_configuration#licensing) + +## Author + +[Tom Page](https://github.com/Tompage1994) diff --git a/collections/controller_configuration/controller_host_groups.md b/collections/controller_configuration/controller_host_groups.md new file mode 100644 index 0000000..1d91d42 --- /dev/null +++ b/collections/controller_configuration/controller_host_groups.md @@ -0,0 +1,179 @@ +--- +layout: default +title: controller_host_groups +parent: infra.controller_configuration +--- + +# controller_configuration.groups + +## Description + +An Ansible Role to create/update/remove Groups on Ansible Controller. + +## Requirements + +ansible-galaxy collection install -r tests/collections/requirements.yml to be installed +Currently: + awx.awx + or + ansible.controller + +## Variables + +|Variable Name|Default Value|Required|Description|Example| +|`platform_state`|"present"|no|The state all objects will take unless overridden by object default|'absent'| +|`aap_hostname`|""|yes|URL to the Ansible Automation Platform Server.|127.0.0.1| +|`aap_validate_certs`|`True`|no|Whether or not to validate the Ansible Automation Platform Server's SSL certificate.|| +|`aap_username`|""|no|Admin User on the Ansible Automation Platform Server. Either username / password or oauthtoken need to be specified.|| +|`aap_password`|""|no|Platform Admin User's password on the Server. This should be stored in an Ansible Vault at vars/platform-secrets.yml or elsewhere and called from a parent playbook.|| +|`aap_token`|""|no|Controller Admin User's token on the Ansible Automation Platform Server. This should be stored in an Ansible Vault at or elsewhere and called from a parent playbook. Either username / password or oauthtoken need to be specified.|| +|`aap_request_timeout`|`10`|no|Specify the timeout in seconds Ansible should use in requests to the Ansible Automation Platform host.|| +|`controller_groups`|`see below`|yes|Data structure describing your group or groups Described below.|| + +### Enforcing defaults + +The following Variables compliment each other. +If Both variables are not set, enforcing default values is not done. +Enabling these variables enforce default values on options that are optional in the controller API. +This should be enabled to enforce configuration and prevent configuration drift. It is recomended to be enabled, however it is not enforced by default. + +Enabling this will enforce configurtion without specifying every option in the configuration files. + +'controller_configuration_groups_enforce_defaults' defaults to the value of 'aap_configuration_enforce_defaults' if it is not explicitly called. This allows for enforced defaults to be toggled for the entire suite of controller configuration roles with a single variable, or for the user to selectively use it. + +|Variable Name|Default Value|Required|Description| +|`controller_configuration_groups_enforce_defaults`|`False`|no|Whether or not to enforce default option values on only the applications role| +|`aap_configuration_enforce_defaults`|`False`|no|This variable enables enforced default values as well, but is shared across multiple roles, see above.| + +### Secure Logging Variables + +The following Variables compliment each other. +If Both variables are not set, secure logging defaults to false. +The role defaults to False as normally the add groups task does not include sensitive information. +controller_configuration_groups_secure_logging defaults to the value of aap_configuration_secure_logging if it is not explicitly called. This allows for secure logging to be toggled for the entire suite of configuration roles with a single variable, or for the user to selectively use it. + +|Variable Name|Default Value|Required|Description| +|`controller_configuration_groups_secure_logging`|`False`|no|Whether or not to include the sensitive Group role tasks in the log. Set this value to `True` if you will be providing your sensitive values from elsewhere.| +|`aap_configuration_secure_logging`|`False`|no|This variable enables secure logging as well, but is shared across multiple roles, see above.| + +### Asynchronous Retry Variables + +The following Variables set asynchronous retries for the role. +If neither of the retries or delay or retries are set, they will default to their respective defaults. +This allows for all items to be created, then checked that the task finishes successfully. +This also speeds up the overall role. + +|Variable Name|Default Value|Required|Description| +|`aap_configuration_async_retries`|30|no|This variable sets the number of retries to attempt for the role globally.| +|`controller_configuration_groups_async_retries`|`{{ aap_configuration_async_retries }}`|no|This variable sets the number of retries to attempt for the role.| +|`aap_configuration_async_delay`|1|no|This sets the delay between retries for the role globally.| +|`controller_configuration_groups_async_delay`|`aap_configuration_async_delay`|no|This sets the delay between retries for the role.| +|`aap_configuration_loop_delay`|0|no|This sets the pause between each item in the loop for the roles globally. To help when API is getting overloaded.| +|`controller_configuration_group_loop_delay`|`aap_configuration_loop_delay`|no|This sets the pause between each item in the loop for the role. To help when API is getting overloaded.| +|`aap_configuration_async_dir`|`null`|no|Sets the directory to write the results file for async tasks. The default value is set to `null` which uses the Ansible Default of `/root/.ansible_async/`.| + +### Formating Variables + +Variables can use a standard Jinja templating format to describe the resource. + +Example: + +```json +{{ variable }} +``` + +Because of this it is difficult to provide controller with the required format for these fields. + +The workaround is to use the following format: + +```json +{ { variable }} +``` + +The role will strip the double space between the curly bracket in order to provide controller with the correct format for the Variables. + +## Data Structure + +### Group Variables + +|Variable Name|Default Value|Required|Type|Description| +|`name`|""|yes|str|Name of Group| +|`new_name`|""|yes|str|Name of Group, used in updating a Group.| +|`description`|`False`|no|str|Description of the Group.| +|`inventory`|""|yes|str|Name of inventory the group should be made a member of.| +|`variables`|{}|no|dict|variables applicable to group.| +|`hosts`|""|no|list|hosts (list) in group| +|`children`|""|no|list|List of groups that should be nested inside in this group| +|`preserve_existing_hosts`|`False`|no|bool|Whether to preserve existing hosts in an existing group| +|`preserve_existing_children`|`False`|no|bool|Whether to preserve existing children in an existing group| +|`state`|`present`|no|str|Desired state of the resource.| + +### Standard Group Data Structure + +#### Json Example + +```json +{ + "controller_groups": [ + { + "name": "PSQL_Servers", + "description": "Default", + "inventory": "Source Control", + "variables": { + "my_var": true + } + } + ] +} +``` + +#### Yaml Example + +```yaml +controller_groups: +- name: PSQL_Servers + description: Group for Postgres SQL Servers + inventory: Default + variables: + myvars: example1 + hosts: + - PSQL1 + - PSQL2 + - PSQL3 + children: + - group1 + - group2 + - group3 +``` + +## Playbook Examples + +### Standard Role Usage + +```yaml +- name: Playbook to configure ansible controller post installation + hosts: localhost + connection: local + # Define following vars here, or in platform_configs/controller_auth.yml + # aap_hostname: ansible-controller-web-svc-test-project.example.com + # aap_username: admin + # aap_password: changeme + pre_tasks: + - name: Include vars from platform_configs directory + ansible.builtin.include_vars: + dir: ./yaml + ignore_files: [controller_config.yml.template] + extensions: ["yml"] + roles: + - {role: infra.aap_configuration.groups, when: controller_groups is defined} +``` + +## License + +[GPL-3.0](https://github.com/redhat-cop/aap_configuration#licensing) + +## Author + +[Wei-Yen Tan](https://github.com/weiyentan) +[Andrew J. Huffman](https://github.com/ahuffman) +[Sean Sullivan](https://github.com/sean-m-sullivan) diff --git a/collections/controller_configuration/controller_hosts.md b/collections/controller_configuration/controller_hosts.md new file mode 100644 index 0000000..f462823 --- /dev/null +++ b/collections/controller_configuration/controller_hosts.md @@ -0,0 +1,165 @@ +--- +layout: default +title: controller_hosts +parent: infra.controller_configuration +--- + +# controller_configuration.hosts + +## Description + +An Ansible Role to add/update/remove hosts on Ansible Controller. + +## Requirements + +ansible-galaxy collection install -r tests/collections/requirements.yml to be installed +Currently: + awx.awx + or + ansible.controller + +## Variables + +|Variable Name|Default Value|Required|Description|Example| +|`platform_state`|"present"|no|The state all objects will take unless overridden by object default|'absent'| +|`aap_hostname`|""|yes|URL to the Ansible Automation Platform Server.|127.0.0.1| +|`aap_validate_certs`|`True`|no|Whether or not to validate the Ansible Automation Platform Server's SSL certificate.|| +|`aap_username`|""|no|Admin User on the Ansible Automation Platform Server. Either username / password or oauthtoken need to be specified.|| +|`aap_password`|""|no|Platform Admin User's password on the Server. This should be stored in an Ansible Vault at vars/platform-secrets.yml or elsewhere and called from a parent playbook.|| +|`aap_token`|""|no|Controller Admin User's token on the Ansible Automation Platform Server. This should be stored in an Ansible Vault at or elsewhere and called from a parent playbook. Either username / password or oauthtoken need to be specified.|| +|`aap_request_timeout`|`10`|no|Specify the timeout in seconds Ansible should use in requests to the Ansible Automation Platform host.|| +|`controller_hosts`|`see below`|yes|Data structure describing your host entries described below.|| + +### Enforcing defaults + +The following Variables compliment each other. +If Both variables are not set, enforcing default values is not done. +Enabling these variables enforce default values on options that are optional in the controller API. +This should be enabled to enforce configuration and prevent configuration drift. It is recomended to be enabled, however it is not enforced by default. + +Enabling this will enforce configurtion without specifying every option in the configuration files. + +'controller_configuration_host_enforce_defaults' defaults to the value of 'aap_configuration_enforce_defaults' if it is not explicitly called. This allows for enforced defaults to be toggled for the entire suite of controller configuration roles with a single variable, or for the user to selectively use it. + +|Variable Name|Default Value|Required|Description| +|`controller_configuration_host_enforce_defaults`|`False`|no|Whether or not to enforce default option values on only the applications role| +|`aap_configuration_enforce_defaults`|`False`|no|This variable enables enforced default values as well, but is shared across multiple roles, see above.| + +### Secure Logging Variables + +The following Variables compliment each other. +If Both variables are not set, secure logging defaults to false. +The role defaults to False as normally the add host task does not include sensitive information. +`controller_configuration_host_secure_logging` defaults to the value of `aap_configuration_secure_logging` if it is not explicitly called. This allows for secure logging to be toggled for the entire suite of configuration roles with a single variable, or for the user to selectively use it. + +|Variable Name|Default Value|Required|Description| +|`controller_configuration_host_secure_logging`|`False`|no|Whether or not to include the sensitive host role tasks in the log. Set this value to `True` if you will be providing your sensitive values from elsewhere.| +|`aap_configuration_secure_logging`|`False`|no|This variable enables secure logging as well, but is shared across multiple roles, see above.| + +### Asynchronous Retry Variables + +The following Variables set asynchronous retries for the role. +If neither of the retries or delay or retries are set, they will default to their respective defaults. +This allows for all items to be created, then checked that the task finishes successfully. +This also speeds up the overall role. + +|Variable Name|Default Value|Required|Description| +|`aap_configuration_async_retries`|30|no|This variable sets the number of retries to attempt for the role globally.| +|`controller_configuration_host_async_retries`|`{{ aap_configuration_async_retries }}`|no|This variable sets the number of retries to attempt for the role.| +|`aap_configuration_async_delay`|1|no|This sets the delay between retries for the role globally.| +|`controller_configuration_host_async_delay`|`aap_configuration_async_delay`|no|This sets the delay between retries for the role.| +|`aap_configuration_loop_delay`|0|no|This sets the pause between each item in the loop for the roles globally. To help when API is getting overloaded.| +|`controller_configuration_hosts_loop_delay`|`aap_configuration_loop_delay`|no|This sets the pause between each item in the loop for the role. To help when API is getting overloaded.| +|`aap_configuration_async_dir`|`null`|no|Sets the directory to write the results file for async tasks. The default value is set to `null` which uses the Ansible Default of `/root/.ansible_async/`.| + +### Formating Variables + +Variables can use a standard Jinja templating format to describe the resource. + +Example: + +```json +{{ variable }} +``` + +Because of this it is difficult to provide controller with the required format for these fields. + +The workaround is to use the following format: + +```json +{ { variable }} +``` + +The role will strip the double space between the curly bracket in order to provide controller with the correct format for the Variables. + +## Data Structure + +### Host Variables + +|Variable Name|Default Value|Required|Type|Description| +|`name`|""|yes|str|The name of the host.| +|`new_name`|""|yes|str|To use when changing a hosts's name.| +|`description`|""|no|str|The description of the host.| +|`inventory`|""|yes|str|The inventory the host applies against.| +|`enabled`||no|bool|If the host should be enabled.| +|`variables`|{}|no|str|The variables applicable to the host.| +|`state`|`present`|no|str|Desired state of the resource.| + +### Standard Host Data Structure + +#### Json Example + +```json +{ + "controller_host": [ + { + "name": "localhost", + "inventory": "My Inv", + "variables": { + "my_var": true + } + } + ] +} +``` + +#### Yaml Example + +```yaml +controller_hosts: + - name: localhost + inventory: localhost + variables: + some_var: some_val + ansible_connection: local +``` + +## Playbook Examples + +### Standard Role Usage + +```yaml +- name: Playbook to configure ansible controller post installation + hosts: localhost + connection: local + # Define following vars here, or in platform_configs/controller_auth.yml + # aap_hostname: ansible-controller-web-svc-test-project.example.com + # aap_username: admin + # aap_password: changeme + pre_tasks: + - name: Include vars from platform_configs directory + ansible.builtin.include_vars: + dir: ./yaml + ignore_files: [controller_config.yml.template] + extensions: ["yml"] + roles: + - {role: infra.aap_configuration.hosts, when: controller_hosts is defined} +``` + +## License + +[GPL-3.0](https://github.com/redhat-cop/aap_configuration#licensing) + +## Author + +[Tom Page](https://github.com/Tompage1994) diff --git a/collections/controller_configuration/controller_instance_groups.md b/collections/controller_configuration/controller_instance_groups.md new file mode 100644 index 0000000..83d14f8 --- /dev/null +++ b/collections/controller_configuration/controller_instance_groups.md @@ -0,0 +1,130 @@ +--- +layout: default +title: controller_instance_groups +parent: infra.controller_configuration +--- + +# controller_configuration.instance_groups + +## Description + +An Ansible Role to create/update/remove instance groups on Ansible Controller. + +## Requirements + +ansible-galaxy collection install -r tests/collections/requirements.yml to be installed +Currently: + awx.awx + or + ansible.controller + +## Variables + +|Variable Name|Default Value|Required|Description|Example| +|`platform_state`|"present"|no|The state all objects will take unless overridden by object default|'absent'| +|`aap_hostname`|""|yes|URL to the Ansible Automation Platform Server.|127.0.0.1| +|`aap_validate_certs`|`True`|no|Whether or not to validate the Ansible Automation Platform Server's SSL certificate.|| +|`aap_username`|""|no|Admin User on the Ansible Automation Platform Server. Either username / password or oauthtoken need to be specified.|| +|`aap_password`|""|no|Platform Admin User's password on the Server. This should be stored in an Ansible Vault at vars/platform-secrets.yml or elsewhere and called from a parent playbook.|| +|`aap_token`|""|no|Controller Admin User's token on the Ansible Automation Platform Server. This should be stored in an Ansible Vault at or elsewhere and called from a parent playbook. Either username / password or oauthtoken need to be specified.|| +|`aap_request_timeout`|`10`|no|Specify the timeout in seconds Ansible should use in requests to the Ansible Automation Platform host.|| +|`controller_instance_groups`|`see below`|yes|Data structure describing your instance groups Described below.|| + +### Enforcing defaults + +The following Variables compliment each other. +If Both variables are not set, enforcing default values is not done. +Enabling these variables enforce default values on options that are optional in the controller API. +This should be enabled to enforce configuration and prevent configuration drift. It is recomended to be enabled, however it is not enforced by default. + +Enabling this will enforce configurtion without specifying every option in the configuration files. + +'controller_configuration_instance_groups_enforce_defaults' defaults to the value of 'aap_configuration_enforce_defaults' if it is not explicitly called. This allows for enforced defaults to be toggled for the entire suite of controller configuration roles with a single variable, or for the user to selectively use it. + +|Variable Name|Default Value|Required|Description| +|`controller_configuration_instance_groups_enforce_defaults`|`False`|no|Whether or not to enforce default option values on only the applications role| +|`aap_configuration_enforce_defaults`|`False`|no|This variable enables enforced default values as well, but is shared across multiple roles, see above.| + +### Secure Logging Variables + +The following Variables compliment each other. +If Both variables are not set, secure logging defaults to false. +The role defaults to False as normally the add instance groups task does not include sensitive information. +controller_configuration_instance_groups_secure_logging defaults to the value of aap_configuration_secure_logging if it is not explicitly called. This allows for secure logging to be toggled for the entire suite of controller configuration roles with a single variable, or for the user to selectively use it. + +|Variable Name|Default Value|Required|Description| +|`controller_configuration_instance_groups_secure_logging`|`False`|no|Whether or not to include the sensitive instance groups role tasks in the log. Set this value to `True` if you will be providing your sensitive values from elsewhere.| +|`aap_configuration_secure_logging`|`False`|no|This variable enables secure logging as well, but is shared across multiple roles, see above.| + +### Asynchronous Retry Variables + +The following Variables set asynchronous retries for the role. +If neither of the retries or delay or retries are set, they will default to their respective defaults. +This allows for all items to be created, then checked that the task finishes successfully. +This also speeds up the overall role. + +|Variable Name|Default Value|Required|Description| +|`aap_configuration_async_retries`|30|no|This variable sets the number of retries to attempt for the role globally.| +|`controller_configuration_instance_groups_async_retries`|`{{ aap_configuration_async_retries }}`|no|This variable sets the number of retries to attempt for the role.| +|`aap_configuration_async_delay`|1|no|This sets the delay between retries for the role globally.| +|`controller_configuration_instance_groups_async_delay`|`aap_configuration_async_delay`|no|This sets the delay between retries for the role.| +|`aap_configuration_loop_delay`|0|no|This sets the pause between each item in the loop for the roles globally. To help when API is getting overloaded.| +|`controller_configuration_instance_groups_loop_delay`|`aap_configuration_loop_delay`|no|This sets the pause between each item in the loop for the role. To help when API is getting overloaded.| +|`aap_configuration_async_dir`|`null`|no|Sets the directory to write the results file for async tasks. The default value is set to `null` which uses the Ansible Default of `/root/.ansible_async/`.| + +## Data Structure + +### Instance Group Variables + +|Variable Name|Default Value|Required|Type|Description| +|`name`|""|yes|str|Name of this instance group.| +|`new_name`|""|str|no|Setting this option will change the existing name (looked up via the name field).| +|`credential`|""|no|str|Credential to authenticate with Kubernetes or OpenShift. Must be of type "Kubernetes/OpenShift API Bearer Token". Will make instance part of a Container Group.| +|`is_container_group`|False|no|bool|Signifies that this InstanceGroup should act as a ContainerGroup. If no credential is specified, the underlying Pod's ServiceAccount will be used.| +|`policy_instance_percentage`|""|no|int|Minimum percentage of all instances that will be automatically assigned to this group when new instances come online.| +|`policy_instance_minimum`|""|no|int|Static minimum number of Instances that will be automatically assign to this group when new instances come online.| +|`policy_instance_list`|""|no|list|List of exact-match Instances that will be assigned to this group.| +|`max_concurrent_jobs`|0|no|int|Maximum number of concurrent jobs to run on this group. Zero means no limit.| +|`max_forks`|0|no|int|Max forks to execute on this group. Zero means no limit.| +|`pod_spec_override`|""|no|str|A custom Kubernetes or OpenShift Pod specification.| +|`instances`|""|no|list|The instances associated with this instance_group.| +|`state`|`present`|no|str|Desired state of the resource.| + +### Standard Instance Group Data Structure + +#### Yaml Example + +```yaml +controller_instance_groups: + - name: test_instance_group +``` + +## Playbook Examples + +### Standard Role Usage + +```yaml +- name: Playbook to configure ansible controller post installation + hosts: localhost + connection: local + # Define following vars here, or in platform_configs/controller_auth.yml + # aap_hostname: ansible-controller-web-svc-test-project.example.com + # aap_username: admin + # aap_password: changeme + pre_tasks: + - name: Include vars from platform_configs directory + ansible.builtin.include_vars: + dir: ./yaml + ignore_files: [controller_config.yml.template] + extensions: ["yml"] + roles: + - {role: infra.aap_configuration.instance_groups, when: controller_instance_groups is defined} +``` + +## License + +[GPL-3.0](https://github.com/redhat-cop/aap_configuration#licensing) + +## Author + +[Sean Sullivan](https://github.com/sean-m-sullivan) diff --git a/collections/controller_configuration/controller_instances.md b/collections/controller_configuration/controller_instances.md new file mode 100644 index 0000000..91fb8c3 --- /dev/null +++ b/collections/controller_configuration/controller_instances.md @@ -0,0 +1,129 @@ +--- +layout: default +title: controller_instances +parent: infra.controller_configuration +--- + +# controller_configuration.instances + +## Description + +An Ansible Role to create instances on Ansible Controller. + +## Requirements + +ansible-galaxy collection install -r tests/collections/requirements.yml to be installed +Currently: + awx.awx + or + ansible.controller + +## Variables + +|Variable Name|Default Value|Required|Description|Example| +|`platform_state`|"present"|no|The state all objects will take unless overridden by object default|'absent'| +|`aap_hostname`|""|yes|URL to the Ansible Automation Platform Server.|127.0.0.1| +|`aap_validate_certs`|`True`|no|Whether or not to validate the Ansible Automation Platform Server's SSL certificate.|| +|`aap_username`|""|no|Admin User on the Ansible Automation Platform Server. Either username / password or oauthtoken need to be specified.|| +|`aap_password`|""|no|Platform Admin User's password on the Server. This should be stored in an Ansible Vault at vars/platform-secrets.yml or elsewhere and called from a parent playbook.|| +|`aap_token`|""|no|Controller Admin User's token on the Ansible Automation Platform Server. This should be stored in an Ansible Vault at or elsewhere and called from a parent playbook. Either username / password or oauthtoken need to be specified.|| +|`aap_request_timeout`|`10`|no|Specify the timeout in seconds Ansible should use in requests to the Ansible Automation Platform host.|| +|`controller_instances`|`see below`|yes|Data structure describing your instances Described below.|| + +### Enforcing defaults + +The following Variables compliment each other. +If Both variables are not set, enforcing default values is not done. +Enabling these variables enforce default values on options that are optional in the controller API. +This should be enabled to enforce configuration and prevent configuration drift. It is recomended to be enabled, however it is not enforced by default. + +Enabling this will enforce configurtion without specifying every option in the configuration files. + +'controller_configuration_instances_enforce_defaults' defaults to the value of 'aap_configuration_enforce_defaults' if it is not explicitly called. This allows for enforced defaults to be toggled for the entire suite of controller configuration roles with a single variable, or for the user to selectively use it. + +|Variable Name|Default Value|Required|Description| +|`controller_configuration_instances_enforce_defaults`|`False`|no|Whether or not to enforce default option values on only the applications role| +|`aap_configuration_enforce_defaults`|`False`|no|This variable enables enforced default values as well, but is shared across multiple roles, see above.| + +### Secure Logging Variables + +The following Variables compliment each other. +If Both variables are not set, secure logging defaults to false. +The role defaults to False as normally the add instances task does not include sensitive information. +controller_configuration_instances_secure_logging defaults to the value of aap_configuration_secure_logging if it is not explicitly called. This allows for secure logging to be toggled for the entire suite of controller configuration roles with a single variable, or for the user to selectively use it. + +|Variable Name|Default Value|Required|Description| +|`controller_configuration_instances_secure_logging`|`False`|no|Whether or not to include the sensitive instance groups role tasks in the log. Set this value to `True` if you will be providing your sensitive values from elsewhere.| +|`aap_configuration_secure_logging`|`False`|no|This variable enables secure logging as well, but is shared across multiple roles, see above.| + +### Asynchronous Retry Variables + +The following Variables set asynchronous retries for the role. +If neither of the retries or delay or retries are set, they will default to their respective defaults. +This allows for all items to be created, then checked that the task finishes successfully. +This also speeds up the overall role. + +|Variable Name|Default Value|Required|Description| +|`aap_configuration_async_retries`|30|no|This variable sets the number of retries to attempt for the role globally.| +|`controller_configuration_instances_async_retries`|`{{ aap_configuration_async_retries }}`|no|This variable sets the number of retries to attempt for the role.| +|`aap_configuration_async_delay`|1|no|This sets the delay between retries for the role globally.| +|`controller_configuration_instances_async_delay`|`aap_configuration_async_delay`|no|This sets the delay between retries for the role.| +|`aap_configuration_loop_delay`|0|no|This sets the pause between each item in the loop for the roles globally. To help when API is getting overloaded.| +|`controller_configuration_instances_loop_delay`|`aap_configuration_loop_delay`|no|This sets the pause between each item in the loop for the role. To help when API is getting overloaded.| +|`aap_configuration_async_dir`|`null`|no|Sets the directory to write the results file for async tasks. The default value is set to `null` which uses the Ansible Default of `/root/.ansible_async/`.| + +## Data Structure + +### Instance Variables + +|Variable Name|Default Value|Required|Type|Description| +|`hostname`|""|yes|str|Hostname of this instance.| +|`capacity_adjustment`|""|float|no|Capacity adjustment between 0 and 1.| +|`enabled`|False|no|bool|If true, the instance will be enabled and used.| +|`managed_by_policy`|False|no|bool|If true, will be managed by instance group policy.| +|`node_type`|""|no|str|Role that this node plays in the mesh. Most likely Execution. Current options are 'execution'.| +|`node_state`|""|no|str|Indicates the current life cycle stage of this instance. Current options are 'installed' and 'deprovisioning'.| +|`listener_port`|""|no|int|Port that Receptor will listen for incoming connections on.| +|`peers`|[]|no|list|List of peers to connect outbound to. Only configurable for hop and execution nodes.| +|`peers_from_control_nodes`|False|no|bool|If enabled, control plane nodes will automatically peer to this node.| + +### Standard Instance Data Structure + +#### Yaml Example + +```yaml +controller_instances: + - hostname: my-instance.prod.example.com + capacity_adjustment: 0.4 + listener_port: 31337 +``` + +## Playbook Examples + +### Standard Role Usage + +```yaml +- name: Playbook to configure ansible controller post installation + hosts: localhost + connection: local + # Define following vars here, or in platform_configs/controller_auth.yml + # aap_hostname: ansible-controller-web-svc-test-project.example.com + # aap_username: admin + # aap_password: changeme + pre_tasks: + - name: Include vars from platform_configs directory + ansible.builtin.include_vars: + dir: ./yaml + ignore_files: [controller_config.yml.template] + extensions: ["yml"] + roles: + - {role: infra.aap_configuration.instances, when: controller_instances is defined} +``` + +## License + +[GPL-3.0](https://github.com/redhat-cop/aap_configuration#licensing) + +## Author + +[Sean Sullivan](https://github.com/sean-m-sullivan) diff --git a/collections/controller_configuration/controller_inventories.md b/collections/controller_configuration/controller_inventories.md new file mode 100644 index 0000000..094184a --- /dev/null +++ b/collections/controller_configuration/controller_inventories.md @@ -0,0 +1,184 @@ +--- +layout: default +title: controller_inventories +parent: infra.controller_configuration +--- + +# controller_configuration.inventories + +## Description + +An Ansible Role to create/update/remove inventories on Ansible Controller. + +## Requirements + +ansible-galaxy collection install -r tests/collections/requirements.yml to be installed +Currently: + awx.awx + or + ansible.controller + +## Variables + +|Variable Name|Default Value|Required|Description|Example| +|`platform_state`|"present"|no|The state all objects will take unless overridden by object default|'absent'| +|`aap_hostname`|""|yes|URL to the Ansible Automation Platform Server.|127.0.0.1| +|`aap_validate_certs`|`True`|no|Whether or not to validate the Ansible Automation Platform Server's SSL certificate.|| +|`aap_username`|""|no|Admin User on the Ansible Automation Platform Server. Either username / password or oauthtoken need to be specified.|| +|`aap_password`|""|no|Platform Admin User's password on the Server. This should be stored in an Ansible Vault at vars/platform-secrets.yml or elsewhere and called from a parent playbook.|| +|`aap_token`|""|no|Controller Admin User's token on the Ansible Automation Platform Server. This should be stored in an Ansible Vault at or elsewhere and called from a parent playbook. Either username / password or oauthtoken need to be specified.|| +|`aap_request_timeout`|`10`|no|Specify the timeout in seconds Ansible should use in requests to the Ansible Automation Platform host.|| +|`controller_inventories`|`see below`|yes|Data structure describing your inventories described below. Alias: inventory || + +### Enforcing defaults + +The following Variables compliment each other. +If Both variables are not set, enforcing default values is not done. +Enabling these variables enforce default values on options that are optional in the controller API. +This should be enabled to enforce configuration and prevent configuration drift. It is recomended to be enabled, however it is not enforced by default. + +Enabling this will enforce configurtion without specifying every option in the configuration files. + +'controller_configuration_inventories_enforce_defaults' defaults to the value of 'aap_configuration_enforce_defaults' if it is not explicitly called. This allows for enforced defaults to be toggled for the entire suite of controller configuration roles with a single variable, or for the user to selectively use it. + +|Variable Name|Default Value|Required|Description| +|`controller_configuration_inventories_enforce_defaults`|`False`|no|Whether or not to enforce default option values on only the applications role| +|`aap_configuration_enforce_defaults`|`False`|no|This variable enables enforced default values as well, but is shared across multiple roles, see above.| + +### Secure Logging Variables + +The following Variables compliment each other. +If Both variables are not set, secure logging defaults to false. +The role defaults to False as normally the add inventories task does not include sensitive information. +controller_configuration_inventories_secure_logging defaults to the value of aap_configuration_secure_logging if it is not explicitly called. This allows for secure logging to be toggled for the entire suite of configuration roles with a single variable, or for the user to selectively use it. + +|Variable Name|Default Value|Required|Description| +|`controller_configuration_inventories_secure_logging`|`False`|no|Whether or not to include the sensitive Inventory role tasks in the log. Set this value to `True` if you will be providing your sensitive values from elsewhere.| +|`aap_configuration_secure_logging`|`False`|no|This variable enables secure logging as well, but is shared across multiple roles, see above.| + +### Asynchronous Retry Variables + +The following Variables set asynchronous retries for the role. +If neither of the retries or delay or retries are set, they will default to their respective defaults. +This allows for all items to be created, then checked that the task finishes successfully. +This also speeds up the overall role. + +|Variable Name|Default Value|Required|Description| +|`aap_configuration_async_retries`|30|no|This variable sets the number of retries to attempt for the role globally.| +|`controller_configuration_inventories_async_retries`|`{{ aap_configuration_async_retries }}`|no|This variable sets the number of retries to attempt for the role.| +|`aap_configuration_async_delay`|1|no|This sets the delay between retries for the role globally.| +|`controller_configuration_inventories_async_delay`|`aap_configuration_async_delay`|no|This sets the delay between retries for the role.| +|`aap_configuration_loop_delay`|0|no|This sets the pause between each item in the loop for the roles globally. To help when API is getting overloaded.| +|`controller_configuration_inventories_loop_delay`|`aap_configuration_loop_delay`|no|This sets the pause between each item in the loop for the role. To help when API is getting overloaded.| +|`aap_configuration_async_dir`|`null`|no|Sets the directory to write the results file for async tasks. The default value is set to `null` which uses the Ansible Default of `/root/.ansible_async/`.| + +### Formating Variables + +Variables can use a standard Jinja templating format to describe the resource. + +Example: + +```json +{{ variable }} +``` + +Because of this it is difficult to provide controller with the required format for these fields. + +The workaround is to use the following format: + +```json +{ { variable }} +``` + +The role will strip the double space between the curly bracket in order to provide controller with the correct format for the Variables. + +## Data Structure + +### Inventory Variables + +|Variable Name|Default Value|Required|type|Description| +|`name`|""|yes|str|Name of this inventory.| +|`new_name`|""|no|str|Setting this option will change the existing name (looked up via the name field).| +|`copy_from`|""|no|str|Name or id to copy the inventory from. This will copy an existing inventory and change any parameters supplied.| +|`description`|""|no|str|Description of this inventory.| +|`organization`|""|yes|str|Organization this inventory belongs to.| +|`instance_groups`|""|no|list|List of Instance Groups for this Inventory to run on.| +|`input_inventories`|""|no|list|List of Inventories to use as input for Constructed Inventory.| +|`variables`|`{}`|no|dict|Variables for the inventory.| +|`kind`|""|no|str|The kind of inventory. Currently choices are '' and 'smart'| +|`host_filter`|""|no|str|The host filter field, useful only when 'kind=smart'| +|`prevent_instance_group_fallback`|`False`|no|bool|Prevent falling back to instance groups set on the organization| +|`state`|`present`|no|str|Desired state of the resource.| + +### Standard Inventory Data Structure + +#### Json Example + +```json +{ + "controller_inventories": [ + { + "name": "RHVM-01", + "organization": "Satellite", + "description": "created by Ansible Playbook - for RHVM-01" + }, + { + "name": "Test Inventory - Smart", + "organization": "Default", + "description": "created by Ansible Playbook", + "kind": "smart", + "host_filter": "name__icontains=localhost" + } + ] +} + +``` + +#### Yaml Example + +```yaml +controller_inventories: + - name: RHVM-01 + organization: Satellite + description: created by Ansible Playbook - for RHVM-01 + - name: Test Inventory - Smart + organization: Default + description: created by Ansible Playbook + kind: smart + host_filter: "name__icontains=localhost" + +``` + +## Playbook Examples + +### Standard Role Usage + +```yaml +- name: Playbook to configure ansible controller post installation + hosts: localhost + connection: local + # Define following vars here, or in platform_configs/controller_auth.yml + # aap_hostname: ansible-controller-web-svc-test-project.example.com + # aap_username: admin + # aap_password: changeme + pre_tasks: + - name: Include vars from platform_configs directory + ansible.builtin.include_vars: + dir: ./yaml + ignore_files: [controller_config.yml.template] + extensions: ["yml"] + roles: + - {role: infra.aap_configuration.inventories, when: controller_inventories is defined} +``` + +## License + +[GPL-3.0](https://github.com/redhat-cop/aap_configuration#licensing) + +## Author + +[Edward Quail](mailto:equail@redhat.com) + +[Andrew J. Huffman](https://github.com/ahuffman) + +[Kedar Kulkarni](https://github.com/kedark3) diff --git a/collections/controller_configuration/controller_inventory_source_update.md b/collections/controller_configuration/controller_inventory_source_update.md new file mode 100644 index 0000000..5b9c597 --- /dev/null +++ b/collections/controller_configuration/controller_inventory_source_update.md @@ -0,0 +1,121 @@ +--- +layout: default +title: controller_inventory_source_update +parent: infra.controller_configuration +--- + +# controller_configuration.inventory_source_update + +## Description + +An Ansible Role to update a list of inventory sources on Ansible Controller. + +## Requirements + +ansible-galaxy collection install -r tests/collections/requirements.yml to be installed +Currently: + awx.awx + or + ansible.controller + +## Variables + +|Variable Name|Default Value|Required|Description|Example| +|`platform_state`|"present"|no|The state all objects will take unless overridden by object default|'absent'| +|`aap_hostname`|""|yes|URL to the Ansible Automation Platform Server.|127.0.0.1| +|`aap_validate_certs`|`True`|no|Whether or not to validate the Ansible Automation Platform Server's SSL certificate.|| +|`aap_username`|""|no|Admin User on the Ansible Automation Platform Server. Either username / password or oauthtoken need to be specified.|| +|`aap_password`|""|no|Platform Admin User's password on the Server. This should be stored in an Ansible Vault at vars/platform-secrets.yml or elsewhere and called from a parent playbook.|| +|`aap_token`|""|no|Controller Admin User's token on the Ansible Automation Platform Server. This should be stored in an Ansible Vault at or elsewhere and called from a parent playbook. Either username / password or oauthtoken need to be specified.|| +|`aap_request_timeout`|`10`|no|Specify the timeout in seconds Ansible should use in requests to the Ansible Automation Platform host.|| +|`controller_inventory_sources`|`see below`|yes|Data structure describing controller inventory sources to update Described below. Alias: inventory_sources || + +### Secure Logging Variables + +The following Variables compliment each other. +If Both variables are not set, secure logging defaults to false. +The role defaults to False as normally the inventory source update task does not include sensitive information. +controller_configuration_inventory_source_update_secure_logging defaults to the value of aap_configuration_secure_logging if it is not explicitly called. This allows for secure logging to be toggled for the entire suite of controller configuration roles with a single variable, or for the user to selectively use it. + +|Variable Name|Default Value|Required|Description| +|`controller_configuration_inventory_source_update_secure_logging`|`False`|no|Whether or not to include the sensitive ad_hoc_command role tasks in the log. Set this value to `True` if you will be providing your sensitive values from elsewhere.| +|`aap_configuration_secure_logging`|`False`|no|This variable enables secure logging as well, but is shared across multiple roles, see above.| + +### Asynchronous Retry Variables + +The following Variables set asynchronous retries for the role. +If neither of the retries or delay or retries are set, they will default to their respective defaults. +This allows for all items to be created, then checked that the task finishes successfully. +This also speeds up the overall role. + +|Variable Name|Default Value|Required|Description| +|`aap_configuration_async_retries`|30|no|This variable sets the number of retries to attempt for the role globally.| +|`controller_configuration_inventory_source_update_async_retries`|`aap_configuration_async_retries`|no|This variable sets the number of retries to attempt for the role.| +|`aap_configuration_async_delay`|1|no|This sets the delay between retries for the role globally.| +|`controller_configuration_inventory_source_update_async_delay`|`aap_configuration_async_delay`|no|This sets the delay between retries for the role.| +|`aap_configuration_loop_delay`|0|no|This sets the pause between each item in the loop for the roles globally. To help when API is getting overloaded.| +|`controller_configuration_inventory_source_update_loop_delay`|`aap_configuration_loop_delay`|no|This sets the pause between each item in the loop for the role. To help when API is getting overloaded.| +|`aap_configuration_async_dir`|`null`|no|Sets the directory to write the results file for async tasks. The default value is set to `null` which uses the Ansible Default of `/root/.ansible_async/`.| + +## Data Structure + +### Inventory Source Update Variables + +|Variable Name|Default Value|Required|Type|Description| +|`name`|""|yes|str|The name or id of the inventory source to update.| +|`inventory`|""|yes|str|Name or id of the inventory that contains the inventory source(s) to update.| +|`organization`|""|no|str|Name of the inventory source's inventory's organization.| +|`wait`|""|no|bool|Wait for the job to complete.| +|`interval`|`controller_configuration_inventory_source_update_async_delay`|no|int|The interval to request an update from controller.| +|`timeout`|""|no|int|If waiting for the job to complete this will abort after this amount of seconds.| + +### Standard Inventory Source Update Data Structure + +#### Yaml Example + +```yaml +controller_inventory_sources: + - name: RHVM-01 + source: scm + source_project: Test Inventory source project + source_path: phillips_hue/hosts + inventory: RHVM-01 + organization: Satellite + credential: admin@internal-RHVM-01 + overwrite: true + update_on_launch: true + update_cache_timeout: 0 + wait: true + +``` + +## Playbook Examples + +### Standard Role Usage + +```yaml +- name: Playbook to configure ansible controller post installation + hosts: localhost + connection: local + # Define following vars here, or in platform_configs/controller_auth.yml + # aap_hostname: ansible-controller-web-svc-test-project.example.com + # aap_username: admin + # aap_password: changeme + pre_tasks: + - name: Include vars from platform_configs directory + ansible.builtin.include_vars: + dir: ./yaml + ignore_files: [controller_config.yml.template] + extensions: ["yml"] + roles: + - {role: infra.aap_configuration.inventory_source_update, when: controller_inventory_sources is defined} + +``` + +## License + +[GPL-3.0](https://github.com/redhat-cop/aap_configuration#licensing) + +## Author + +[Sean Sullivan](https://github.com/sean-m-sullivan) diff --git a/collections/controller_configuration/controller_inventory_sources.md b/collections/controller_configuration/controller_inventory_sources.md new file mode 100644 index 0000000..d318474 --- /dev/null +++ b/collections/controller_configuration/controller_inventory_sources.md @@ -0,0 +1,197 @@ +--- +layout: default +title: controller_inventory_sources +parent: infra.controller_configuration +--- + +# controller_configuration.inventory_sources + +## Description + +An Ansible Role to create/update/remove inventory sources on Ansible Controller. + +## Requirements + +ansible-galaxy collection install -r tests/collections/requirements.yml to be installed +Currently: + awx.awx + or + ansible.controller + +## Variables + +|Variable Name|Default Value|Required|Description|Example| +|`platform_state`|"present"|no|The state all objects will take unless overridden by object default|'absent'| +|`aap_hostname`|""|yes|URL to the Ansible Automation Platform Server.|127.0.0.1| +|`aap_validate_certs`|`True`|no|Whether or not to validate the Ansible Automation Platform Server's SSL certificate.|| +|`aap_username`|""|no|Admin User on the Ansible Automation Platform Server. Either username / password or oauthtoken need to be specified.|| +|`aap_password`|""|no|Platform Admin User's password on the Server. This should be stored in an Ansible Vault at vars/platform-secrets.yml or elsewhere and called from a parent playbook.|| +|`aap_token`|""|no|Controller Admin User's token on the Ansible Automation Platform Server. This should be stored in an Ansible Vault at or elsewhere and called from a parent playbook. Either username / password or oauthtoken need to be specified.|| +|`aap_request_timeout`|`10`|no|Specify the timeout in seconds Ansible should use in requests to the Ansible Automation Platform host.|| +|`controller_inventory_sources`|`see below`|yes|Data structure describing your inventory sources Described below. Alias: inventory_sources || + +### Enforcing defaults + +The following Variables compliment each other. +If Both variables are not set, enforcing default values is not done. +Enabling these variables enforce default values on options that are optional in the controller API. +This should be enabled to enforce configuration and prevent configuration drift. It is recomended to be enabled, however it is not enforced by default. + +Enabling this will enforce configurtion without specifying every option in the configuration files. + +'controller_configuration_inventory_sources_enforce_defaults' defaults to the value of 'aap_configuration_enforce_defaults' if it is not explicitly called. This allows for enforced defaults to be toggled for the entire suite of controller configuration roles with a single variable, or for the user to selectively use it. + +|Variable Name|Default Value|Required|Description| +|`controller_configuration_inventory_sources_enforce_defaults`|`False`|no|Whether or not to enforce default option values on only the applications role| +|`aap_configuration_enforce_defaults`|`False`|no|This variable enables enforced default values as well, but is shared across multiple roles, see above.| + +### Secure Logging Variables + +The following Variables compliment each other. +If Both variables are not set, secure logging defaults to false. +The role defaults to False as normally the add inventory_source task does not include sensitive information. +controller_configuration_inventory_sources_secure_logging defaults to the value of aap_configuration_secure_logging if it is not explicitly called. This allows for secure logging to be toggled for the entire suite of configuration roles with a single variable, or for the user to selectively use it. + +|Variable Name|Default Value|Required|Description| +|`controller_configuration_inventory_sources_secure_logging`|`False`|no|Whether or not to include the sensitive Inventory Sources role tasks in the log. Set this value to `True` if you will be providing your sensitive values from elsewhere.| +|`aap_configuration_secure_logging`|`False`|no|This variable enables secure logging as well, but is shared across multiple roles, see above.| + +### Asynchronous Retry Variables + +The following Variables set asynchronous retries for the role. +If neither of the retries or delay or retries are set, they will default to their respective defaults. +This allows for all items to be created, then checked that the task finishes successfully. +This also speeds up the overall role. + +|Variable Name|Default Value|Required|Description| +|`aap_configuration_async_retries`|30|no|This variable sets the number of retries to attempt for the role globally.| +|`controller_configuration_inventory_sources_async_retries`|`{{ aap_configuration_async_retries }}`|no|This variable sets the number of retries to attempt for the role.| +|`aap_configuration_async_delay`|1|no|This sets the delay between retries for the role globally.| +|`controller_configuration_inventory_sources_async_delay`|`aap_configuration_async_delay`|no|This sets the delay between retries for the role.| +|`aap_configuration_loop_delay`|0|no|This sets the pause between each item in the loop for the roles globally. To help when API is getting overloaded.| +|`controller_configuration_inventory_loop_delay`|`aap_configuration_loop_delay`|no|This sets the pause between each item in the loop for the role. To help when API is getting overloaded.| +|`aap_configuration_async_dir`|`null`|no|Sets the directory to write the results file for async tasks. The default value is set to `null` which uses the Ansible Default of `/root/.ansible_async/`.| + +### Formating Variables + +Variables can use a standard Jinja templating format to describe the resource. + +Example: + +```json +{{ variable }} +``` + +Because of this it is difficult to provide controller with the required format for these fields. + +The workaround is to use the following format: + +```json +{ { variable }} +``` + +The role will strip the double space between the curly bracket in order to provide controller with the correct format for the Variables. + +## Data Structure + +### Inventory Sources Variables + +|Variable Name|Default Value|Required|Description| +|`name`|""|yes|The name to use for the inventory source.| +|`new_name`|""|no|A new name for this assets (will rename the asset).| +|`description`|`False`|no|The description to use for the inventory source.| +|`inventory`|""|yes|Inventory the group should be made a member of.| +|`organization`|""|no|Organization the inventory belongs to.| +|`source`|""|no|The source to use for this group. If set to `constructed` this role will be skipped as they are not meant to be edited.| +|`source_path`|""|no|For an SCM based inventory source, the source path points to the file within the repo to use as an inventory.| +|`source_vars`|""|no|The variables or environment fields to apply to this source type.| +|`enabled_var`|""|no|The variable to use to determine enabled state e.g., "status.power_state".| +|`enabled_value`|""|no|Value when the host is considered enabled, e.g., "powered_on".| +|`host_filter`|""|no|If specified, controller will only import hosts that match this regular expression.| +|`limit`|""|no|Enter host, group or pattern match.| +|`credential`|""|no|Credential to use for the source.| +|`execution_environment`|""|no|Execution Environment to use for the source.| +|`overwrite`|""|no|Delete child groups and hosts not found in source.| +|`overwrite_vars`|""|no|Override vars in child groups and hosts with those from external source.| +|`custom_virtualenv`|""|no|Local absolute file path containing a custom Python virtualenv to use.| +|`timeout`|""|no|The amount of time (in seconds) to run before the task is canceled.| +|`verbosity`|""|no|The verbosity level to run this inventory source under.| +|`update_on_launch`|""|no|Refresh inventory data from its source each time a job is run.| +|`update_cache_timeout`|""|no|Time in seconds to consider an inventory sync to be current.| +|`source_project`|""|no|Project to use as source with scm option.| +|`scm_branch`|""|no|Project scm branch to use as source with scm option. Project must have branch override enabled.| +|`state`|`present`|no|Desired state of the resource.| +|`notification_templates_started`|""|no|The notifications on started to use for this inventory source in a list.| +|`notification_templates_success`|""|no|The notifications on success to use for this inventory source in a list.| +|`notification_templates_error`|""|no|The notifications on error to use for this inventory source in a list.| + +### Standard Inventory Source Data Structure + +#### Json Example + +```json +{ + "controller_inventory_sources": [ + { + "name": "RHVM-01", + "source": "rhv", + "inventory": "RHVM-01", + "credential": "admin@internal-RHVM-01", + "description": "created by Ansible controller", + "overwrite": true, + "update_on_launch": true, + "update_cache_timeout": 0 + } + ] +} + +``` + +#### Yaml Example + +```yaml +controller_inventory_sources: + - name: RHVM-01 + source: rhv + inventory: RHVM-01 + credential: admin@internal-RHVM-01 + description: created by Ansible controller + overwrite: true + update_on_launch: true + update_cache_timeout: 0 + +``` + +## Playbook Examples + +### Standard Role Usage + +```yaml +- name: Playbook to configure ansible controller post installation + hosts: localhost + connection: local + # Define following vars here, or in platform_configs/controller_auth.yml + # aap_hostname: ansible-controller-web-svc-test-project.example.com + # aap_username: admin + # aap_password: changeme + pre_tasks: + - name: Include vars from platform_configs directory + ansible.builtin.include_vars: + dir: ./yaml + ignore_files: [controller_config.yml.template] + extensions: ["yml"] + roles: + - {role: infra.aap_configuration.inventory_sources, when: controller_inventory_sources is defined} +``` + +## License + +[GPL-3.0](https://github.com/redhat-cop/aap_configuration#licensing) + +## Author + +[Edward Quail](mailto:equail@redhat.com) + +[Andrew J. Huffman](https://github.com/ahuffman) + +[Kedar Kulkarni](https://github.com/kedark3) diff --git a/collections/controller_configuration/controller_job_launch.md b/collections/controller_configuration/controller_job_launch.md new file mode 100644 index 0000000..844c15d --- /dev/null +++ b/collections/controller_configuration/controller_job_launch.md @@ -0,0 +1,110 @@ +--- +layout: default +title: controller_job_launch +parent: infra.controller_configuration +--- + +# controller_configuration.job_launch + +## Description + +An Ansible Role to launch a job template on Ansible Controller. + +## Requirements + +ansible-galaxy collection install -r tests/collections/requirements.yml to be installed +Currently: + awx.awx + or + ansible.controller + +## Variables + +|Variable Name|Default Value|Required|Description|Example| +|`platform_state`|"present"|no|The state all objects will take unless overridden by object default|'absent'| +|`aap_hostname`|""|yes|URL to the Ansible Automation Platform Server.|127.0.0.1| +|`aap_validate_certs`|`True`|no|Whether or not to validate the Ansible Automation Platform Server's SSL certificate.|| +|`aap_username`|""|no|Admin User on the Ansible Automation Platform Server. Either username / password or oauthtoken need to be specified.|| +|`aap_password`|""|no|Platform Admin User's password on the Server. This should be stored in an Ansible Vault at vars/platform-secrets.yml or elsewhere and called from a parent playbook.|| +|`aap_token`|""|no|Controller Admin User's token on the Ansible Automation Platform Server. This should be stored in an Ansible Vault at or elsewhere and called from a parent playbook. Either username / password or oauthtoken need to be specified.|| +|`aap_request_timeout`|`10`|no|Specify the timeout in seconds Ansible should use in requests to the Ansible Automation Platform host.|| +|`controller_launch_jobs`|`see below`|yes|Data structure describing the jobs to launch Described below.|| + +### Secure Logging Variables + +The following Variables compliment each other. +If Both variables are not set, secure logging defaults to false. +The role defaults to False as normally the job launch task does not include sensitive information. +controller_configuration_job_launch_secure_logging defaults to the value of aap_configuration_secure_logging if it is not explicitly called. This allows for secure logging to be toggled for the entire suite of controller configuration roles with a single variable, or for the user to selectively use it. + +|Variable Name|Default Value|Required|Description| +|`controller_configuration_job_launch_secure_logging`|`False`|no|Whether or not to include the sensitive ad_hoc_command role tasks in the log. Set this value to `True` if you will be providing your sensitive values from elsewhere.| +|`aap_configuration_secure_logging`|`False`|no|This variable enables secure logging as well, but is shared across multiple roles, see above.| + +## Data Structure + +### Job Launch Variables + +|Variable Name|Default Value|Required|Type|Description| +|`name`|""|yes|str|The name or id of the job to launch.| +|`job_type`|""|no|str|Job_type to use for the job, only used if prompt for job_type is set. Run or Check are the options.| +|`inventory`|""|no|str|Inventory to use for the job, only used if prompt for inventory is set.| +|`organization`|""|no|str|Organization the inventory belongs to.| +|`credentials`|""|no|list|TCredential to use for job, only used if prompt for credential is set.| +|`extra_vars`|""|no|dict|extra_vars to use for the Job Template. ask_extra_vars needs to be set to True via controller_job_template module.| +|`limit`|""|no|str|Limit to use for the job_template.| +|`tags`|""|no|str|Specific tags to use for from playbook.| +|`scm_branch`|""|no|str|A specific of the SCM project to run the template on.| +|`skip_tags`|""|no|str|Specific tags to skip from the playbook.| +|`verbosity`|""|no|int|Verbosity level for this job run.| +|`diff_mode`|""|no|bool|Show the changes made by Ansible tasks where supported.| +|`credential_passwords`|""|no|str|Passwords for credentials which are set to prompt on launch.| +|`execution_environment`|Job Template default|no|str|Execution Environment applied as a prompt. Job Template default used if not set. Only allowed if `ask_execution_environment_on_launch` set to true on Job Template| +|`forks`|Job Template default|no|int|Forks applied as a prompt. Job Template default used if not set. Only allowed if `ask_forks_on_launch` set to true on Job Template| +|`instance_groups`|Job Template default|no|str| List of Instance Groups applied as a prompt. Job Template default used if not set. Only allowed if `ask_instance_groups_on_launch` set to true on Job Template| +|`job_slice_count`|Job Template default|no|int|Job Slice Count to use in the job run. Job Template default used if not set. Only allowed if `ask_job_slice_count_on_launch` set to true on Job Template| +|`labels`|Job Template default|no|list|List of labels to use in the job run. Job Template default used if not set. Only allowed if `ask_labels_on_launch` set to true on Job Template| +|`job_timeout`|Job Template default|no|int|Timeout to use in the job run. Job Template default used if not set. Only allowed if `ask_timeout_on_launch` set to true on Job Template| +|`wait`|""|no|bool|Wait for the job to complete.| +|`interval`|2|no|float|The interval to request an update from controller.| +|`timeout`|""|no|int|If waiting for the job to complete this will abort after this amount of seconds.| + +### Standard Job Launch Data Structure + +#### Yaml Example + +```yaml +controller_launch_jobs: + - name: test-template-1 + +``` + +## Playbook Examples + +### Standard Role Usage + +```yaml +- name: Playbook to configure ansible controller post installation + hosts: localhost + connection: local + # Define following vars here, or in platform_configs/controller_auth.yml + # aap_hostname: ansible-controller-web-svc-test-project.example.com + # aap_username: admin + # aap_password: changeme + pre_tasks: + - name: Include vars from platform_configs directory + ansible.builtin.include_vars: + dir: ./yaml + ignore_files: [controller_config.yml.template] + extensions: ["yml"] + roles: + - {role: infra.aap_configuration.job_launch, when: controller_launch_jobs is defined} +``` + +## License + +[GPL-3.0](https://github.com/redhat-cop/aap_configuration#licensing) + +## Author + +[Sean Sullivan](https://github.com/sean-m-sullivan) diff --git a/collections/controller_configuration/controller_job_templates.md b/collections/controller_configuration/controller_job_templates.md new file mode 100644 index 0000000..5a556f3 --- /dev/null +++ b/collections/controller_configuration/controller_job_templates.md @@ -0,0 +1,305 @@ +--- +layout: default +title: controller_job_templates +parent: infra.controller_configuration +--- + +# controller_configuration.job_templates + +## Description + +An Ansible Role to create/update/remove Job Templates on Ansible Controller. + +## Requirements + +ansible-galaxy collection install -r tests/collections/requirements.yml to be installed +Currently: + awx.awx + or + ansible.controller + +## Variables + +|Variable Name|Default Value|Required|Description|Example| +|`platform_state`|"present"|no|The state all objects will take unless overridden by object default|'absent'| +|`aap_hostname`|""|yes|URL to the Ansible Automation Platform Server.|127.0.0.1| +|`aap_validate_certs`|`True`|no|Whether or not to validate the Ansible Automation Platform Server's SSL certificate.|| +|`aap_username`|""|no|Admin User on the Ansible Automation Platform Server. Either username / password or oauthtoken need to be specified.|| +|`aap_password`|""|no|Platform Admin User's password on the Server. This should be stored in an Ansible Vault at vars/platform-secrets.yml or elsewhere and called from a parent playbook.|| +|`aap_token`|""|no|Controller Admin User's token on the Ansible Automation Platform Server. This should be stored in an Ansible Vault at or elsewhere and called from a parent playbook. Either username / password or oauthtoken need to be specified.|| +|`aap_request_timeout`|`10`|no|Specify the timeout in seconds Ansible should use in requests to the Ansible Automation Platform host.|| +|`controller_templates`|`see below`|yes|Data structure describing your job template or job templates Described below. Alias: job_templates || + +### Enforcing defaults + +The following Variables compliment each other. +If Both variables are not set, enforcing default values is not done. +Enabling these variables enforce default values on options that are optional in the controller API. +This should be enabled to enforce configuration and prevent configuration drift. It is recomended to be enabled, however it is not enforced by default. + +Enabling this will enforce configurtion without specifying every option in the configuration files. + +'controller_configuration_job_templates_enforce_defaults' defaults to the value of 'aap_configuration_enforce_defaults' if it is not explicitly called. This allows for enforced defaults to be toggled for the entire suite of controller configuration roles with a single variable, or for the user to selectively use it. + +|Variable Name|Default Value|Required|Description| +|`controller_configuration_job_templates_enforce_defaults`|`False`|no|Whether or not to enforce default option values on only the applications role| +|`aap_configuration_enforce_defaults`|`False`|no|This variable enables enforced default values as well, but is shared across multiple roles, see above.| + +### Secure Logging Variables + +The following Variables compliment each other. +If Both variables are not set, secure logging defaults to false. +The role defaults to False as normally the add job_template task does not include sensitive information. +controller_configuration_job_templates_secure_logging defaults to the value of aap_configuration_secure_logging if it is not explicitly called. This allows for secure logging to be toggled for the entire suite of configuration roles with a single variable, or for the user to selectively use it. + +|Variable Name|Default Value|Required|Description| +|`controller_configuration_job_templates_secure_logging`|`False`|no|Whether or not to include the sensitive Job Template role tasks in the log. Set this value to `True` if you will be providing your sensitive values from elsewhere.| +|`aap_configuration_secure_logging`|`False`|no|This variable enables secure logging as well, but is shared across multiple roles, see above.| + +### Asynchronous Retry Variables + +The following Variables set asynchronous retries for the role. +If neither of the retries or delay or retries are set, they will default to their respective defaults. +This allows for all items to be created, then checked that the task finishes successfully. +This also speeds up the overall role. + +|Variable Name|Default Value|Required|Description| +|`aap_configuration_async_retries`|30|no|This variable sets the number of retries to attempt for the role globally.| +|`controller_configuration_job_templates_async_retries`|`{{ aap_configuration_async_retries }}`|no|This variable sets the number of retries to attempt for the role.| +|`aap_configuration_async_delay`|1|no|This sets the delay between retries for the role globally.| +|`controller_configuration_job_templates_async_delay`|`aap_configuration_async_delay`|no|This sets the delay between retries for the role.| +|`aap_configuration_loop_delay`|0|no|This sets the pause between each item in the loop for the roles globally. To help when API is getting overloaded.| +|`controller_configuration_job_templates_loop_delay`|`aap_configuration_loop_delay`|no|This sets the pause between each item in the loop for the role. To help when API is getting overloaded.| +|`aap_configuration_async_dir`|`null`|no|Sets the directory to write the results file for async tasks. The default value is set to `null` which uses the Ansible Default of `/root/.ansible_async/`.| + +## Data Structure + +### Job Template Variables + +|Variable Name|Default Value|Required|Type|Description| +|`name`|""|yes|str|Name of Job Template| +|`new_name`|""|str|no|Setting this option will change the existing name (looked up via the name field).| +|`copy_from`|""|no|str|Name or id to copy the job template from. This will copy an existing credential and change any parameters supplied.| +|`description`|`False`|no|str|Description to use for the job template.| +|`execution_environment`|""|no|str|Execution Environment to use for the job template.| +|`job_type`|`run`|no|str|The job type to use for the job template(run, check).| +|`inventory`|""|no|str|Name of the inventory to use for the job template.| +|`organization`|""|no|str|Organization the job template exists in. Used to help lookup the object, cannot be modified using this module. The Organization is inferred from the associated project| +|`project`|""|no|str|Name of the project to use for the job template.| +|`playbook`|""|no|str|Path to the playbook to use for the job template within the project provided.| +|`credentials`|""|no|list|List of credentials to use for the job template.| +|`forks`|""|no|int|The number of parallel or simultaneous processes to use while executing the playbook.| +|`limit`|""|no|str|A host pattern to further constrain the list of hosts managed or affected by the playbook| +|`verbosity`|""|no|int|Control the output level Ansible produces as the playbook runs. 0 - Normal, 1 - Verbose, 2 - More Verbose, 3 - Debug, 4 - Connection Debug .| +|`extra_vars`|""|no|dict|Specify extra_vars for the template.| +|`job_tags`|""|no|str|Comma separated list of the tags to use for the job template.| +|`force_handlers`|""|no|bool|Enable forcing playbook handlers to run even if a task fails.| +|`skip_tags`|""|no|str|Comma separated list of the tags to skip for the job template.| +|`start_at_task`|""|no|str|Start the playbook at the task matching this name.| +|`diff_mode`|""|no|bool|Enable diff mode for the job template | +|`use_fact_cache`|""|no|bool|Enable use of fact caching for the job template.| +|`host_config_key`|""|no|str|Allow provisioning callbacks using this host config key.| +|`ask_scm_branch_on_launch`|""|no|bool|Prompt user for scm branch on launch.| +|`ask_diff_mode_on_launch`|""|no|bool|Prompt user to enable diff mode show changes to files when supported by modules.| +|`ask_variables_on_launch`|""|no|bool|Prompt user for extra_vars on launch.| +|`ask_limit_on_launch`|""|no|bool|Prompt user for a limit on launch.| +|`ask_tags_on_launch`|""|no|bool|Prompt user for job tags on launch.| +|`ask_skip_tags_on_launch`|""|no|bool|Prompt user for job tags to skip on launch.| +|`ask_job_type_on_launch`|""|no|bool|Prompt user for job type on launch.| +|`ask_verbosity_on_launch`|""|no|bool|Prompt user to choose a verbosity level on launch.| +|`ask_inventory_on_launch`|""|no|bool|Prompt user for inventory on launch.| +|`ask_credential_on_launch`|""|no|bool|Prompt user for credential on launch.| +|`ask_execution_environment_on_launch`|""|no|bool|Prompt user for execution environment on launch.| +|`ask_forks_on_launch`|""|no|bool|Prompt user for forks on launch.| +|`ask_instance_groups_on_launch`|""|no|bool|Prompt user for instance groups on launch.| +|`ask_job_slice_count_on_launch`|""|no|bool|Prompt user for job slice count on launch.| +|`ask_labels_on_launch`|""|no|bool|Prompt user for labels on launch.| +|`ask_timeout_on_launch`|""|no|bool|Prompt user for timeout on launch.| +|`prevent_instance_group_fallback`|""|no|bool|Prevent falling back to instance groups set on the associated inventory or organization.| +|`survey_enabled`|""|no|bool|Enable a survey on the job template.| +|`survey_spec`|""|no|dict|JSON/YAML dict formatted survey definition.| +|`survey`|""|no|dict|JSON/YAML dict formatted survey definition. Alias of survey_spec| +|`become_enabled`|""|no|bool|Activate privilege escalation.| +|`allow_simultaneous`|""|no|bool|Allow simultaneous runs of the job template.| +|`timeout`|""|no|int|Maximum time in seconds to wait for a job to finish (server-side).| +|`instance_groups`|""|no|list|list of Instance Groups for this Job Template to run on.| +|`job_slice_count`|""|no|int|The number of jobs to slice into at runtime. Will cause the Job Template to launch a workflow if value is greater than 1.| +|`webhook_service`|""|no|str|Service that webhook requests will be accepted from (github, gitlab)| +|`webhook_credential`|""|no|str|Personal Access Token for posting back the status to the service API| +|`scm_branch`|""|no|str|Branch to use in job run. Project default used if blank. Only allowed if project allow_override field is set to true.| +|`labels`|""|no|list|The labels applied to this job template. NOTE: Labels must be created with the [labels](https://github.com/redhat-cop/aap_configuration/tree/devel/roles/controller_labels) role first, an error will occur if the label supplied to this role does not exist.| +|`custom_virtualenv`|""|no|str|Local absolute file path containing a custom Python virtualenv to use.| +|`notification_templates_started`|""|no|list|The notifications on started to use for this organization in a list.| +|`notification_templates_success`|""|no|list|The notifications on success to use for this organization in a list.| +|`notification_templates_error`|""|no|list|The notifications on error to use for this organization in a list.| +|`state`|`present`|no|str|Desired state of the resource.| + +### Surveys + +Refer to the [controller Api Guide](https://docs.ansible.com/ansible-tower/latest/html/towerapi/api_ref.html#/Job_Templates/Job_Templates_job_templates_survey_spec_create) for more information about forming surveys + +|Variable Name|Variable Description| +|`name`|Name of the survey| +|`description`|Description of the survey| +|`spec`|List of survey items, each a dictionary containing the following fields| +|`question_name`|Name of the field/item| +|`question_description`|Longer description| +|`required`|Boolean expressing if an answer is required| +|`type`|One of `text`, `password`, `integer`, `float`, `multiplechoice`or `multiselect`| +|`variable`|Name of Ansible Variable where to put the answer| +|`default`|Default value for the variable| +|`min`|Minimum value for a number type| +|`max`|Maximum value for a number type| +|`choices`|List of choices for a "multi" type| +|`new_question`|Boolean| + +### Standard Job Template Data Structure + +#### Json Example + +```json +{ + "controller_templates": [ + { + "name": "Survey Template with vars", + "job_type": "run", + "inventory": "Demo Inventory", + "survey_enabled": true, + "survey": "{{ lookup('template', 'template_surveys/basic_survey.json') | regex_replace('\\n', '') }}", + "project": "controller Config", + "playbook": "helloworld.yml", + "credentials": [ + "Demo Credential" + ], + "extra_vars": "{{ survey_extra_vars }}", + "notification_templates_error": [ + "Slack_for_testing" + ] + }, + { + "name": "No Survey Template no vars", + "job_type": "run", + "inventory": "Demo Inventory", + "project": "controller Config", + "playbook": "helloworld.yml", + "credentials": [ + "Demo Credential" + ], + "survey": {}, + "extra_vars": "{{ empty_master_vars }}", + "notification_templates_error": [ + "Slack_for_testing" + ] + } + ] +} +``` + +#### Yaml Example + +```yaml +controller_templates: +- name: Survey Template with vars + job_type: run + inventory: Demo Inventory + execution_environment: my_exec_env + survey_enabled: true + survey: "{{ lookup('template', 'template_surveys/basic_survey.json') | regex_replace('\\n', '') }}" + project: controller Config + playbook: helloworld.yml + credentials: + - Demo Credential + extra_vars: "{{ survey_extra_vars }}" + notification_templates_error: + - Slack_for_testing +- name: No Survey Template no vars + job_type: run + inventory: Demo Inventory + project: controller Config + playbook: helloworld.yml + credentials: + - Demo Credential + survey: {} + extra_vars: "{{ empty_master_vars }}" + notification_templates_error: + - Slack_for_testing +``` + +### Survey Data Structure + +#### Survey Json Example + +```json +{ + "name": "Basic Survey", + "description": "Basic Survey", + "spec": [ + { + "question_description": "Name", + "min": 0, + "default": "", + "max": 128, + "required": true, + "choices": "", + "new_question": true, + "variable": "basic_name", + "question_name": "Basic Name", + "type": "text" + }, + { + "question_description": "Choosing yes or no.", + "min": 0, + "default": "yes", + "max": 0, + "required": true, + "choices": "yes\nno", + "new_question": true, + "variable": "option_true_false", + "question_name": "Choose yes or no?", + "type": "multiplechoice" + }, + { + "question_description": "", + "min": 0, + "default": "", + "max": 0, + "required": true, + "choices": "group1\ngroup2\ngroup3", + "new_question": true, + "variable": "target_groups", + "question_name": "Select Group:", + "type": "multiselect" + } + ] + } +``` + +## Playbook Examples + +### Standard Role Usage + +```yaml +- name: Playbook to configure ansible controller post installation + hosts: localhost + connection: local + # Define following vars here, or in platform_configs/controller_auth.yml + # aap_hostname: ansible-controller-web-svc-test-project.example.com + # aap_username: admin + # aap_password: changeme + pre_tasks: + - name: Include vars from platform_configs directory + ansible.builtin.include_vars: + dir: ./yaml + ignore_files: [controller_config.yml.template] + extensions: ["yml"] + roles: + - {role: infra.aap_configuration.job_templates, when: controller_templates is defined} +``` + +## License + +[GPL-3.0](https://github.com/redhat-cop/aap_configuration#licensing) + +## Author + +[Sean Sullivan](https://github.com/sean-m-sullivan) diff --git a/collections/controller_configuration/controller_jobs_cancel.md b/collections/controller_configuration/controller_jobs_cancel.md new file mode 100644 index 0000000..783f10f --- /dev/null +++ b/collections/controller_configuration/controller_jobs_cancel.md @@ -0,0 +1,90 @@ +--- +layout: default +title: controller_jobs_cancel +parent: infra.controller_configuration +--- + +# controller_configuration.jobs_cancel + +## Description + +An Ansible Role to cancel a job on Ansible Controller. + +## Requirements + +ansible-galaxy collection install -r tests/collections/requirements.yml to be installed +Currently: + awx.awx + or + ansible.controller + +## Variables + +|Variable Name|Default Value|Required|Description|Example| +|`platform_state`|"present"|no|The state all objects will take unless overridden by object default|'absent'| +|`aap_hostname`|""|yes|URL to the Ansible Automation Platform Server.|127.0.0.1| +|`aap_validate_certs`|`True`|no|Whether or not to validate the Ansible Automation Platform Server's SSL certificate.|| +|`aap_username`|""|no|Admin User on the Ansible Automation Platform Server. Either username / password or oauthtoken need to be specified.|| +|`aap_password`|""|no|Platform Admin User's password on the Server. This should be stored in an Ansible Vault at vars/platform-secrets.yml or elsewhere and called from a parent playbook.|| +|`aap_token`|""|no|Controller Admin User's token on the Ansible Automation Platform Server. This should be stored in an Ansible Vault at or elsewhere and called from a parent playbook. Either username / password or oauthtoken need to be specified.|| +|`aap_request_timeout`|`10`|no|Specify the timeout in seconds Ansible should use in requests to the Ansible Automation Platform host.|| +|`controller_cancel_jobs`|`see below`|yes|Data structure describing jobs to cancel Described below.|| + +### Secure Logging Variables + +The following Variables compliment each other. +If Both variables are not set, secure logging defaults to false. +The role defaults to False as normally the task to cancel jobs does not include sensitive information. +controller_configuration_jobs_cancel_secure_logging defaults to the value of aap_configuration_secure_logging if it is not explicitly called. This allows for secure logging to be toggled for the entire suite of controller configuration roles with a single variable, or for the user to selectively use it. + +|Variable Name|Default Value|Required|Description| +|`controller_configuration_jobs_cancel_secure_logging`|`False`|no|Whether or not to include the sensitive ad_hoc_command role tasks in the log. Set this value to `True` if you will be providing your sensitive values from elsewhere.| +|`aap_configuration_secure_logging`|`False`|no|This variable enables secure logging as well, but is shared across multiple roles, see above.| + +## Data Structure + +### Cancel Jobs Variables + +|Variable Name|Default Value|Required|Type|Description| +|`id`|""|yes|int|ID of the job to cancel.| +|`fail_if_not_running`|`False`|no|bool|Fail loudly if the job can not be canceled.| + +### Standard Cancel Jobs Data Structure + +#### Yaml Example + +```yaml +controller_cancel_jobs: + - id: 10 + +``` + +## Playbook Examples + +### Standard Role Usage + +```yaml +- name: Playbook to configure ansible controller post installation + hosts: localhost + connection: local + # Define following vars here, or in platform_configs/controller_auth.yml + # aap_hostname: ansible-controller-web-svc-test-project.example.com + # aap_username: admin + # aap_password: changeme + pre_tasks: + - name: Include vars from platform_configs directory + ansible.builtin.include_vars: + dir: ./yaml + ignore_files: [controller_config.yml.template] + extensions: ["yml"] + roles: + - {role: infra.aap_configuration.jobs_cancel, when: controller_cancel_jobs is defined} +``` + +## License + +[GPL-3.0](https://github.com/redhat-cop/aap_configuration#licensing) + +## Author + +[Sean Sullivan](https://github.com/sean-m-sullivan) diff --git a/collections/controller_configuration/controller_labels.md b/collections/controller_configuration/controller_labels.md new file mode 100644 index 0000000..f182982 --- /dev/null +++ b/collections/controller_configuration/controller_labels.md @@ -0,0 +1,127 @@ +--- +layout: default +title: controller_labels +parent: infra.controller_configuration +--- + +# controller_configuration.labels + +An Ansible role to create/update/remove labels for templates on Ansible Controller. + +## Requirements + +ansible-galaxy collection install -r tests/collections/requirements.yml to be installed +Currently: + awx.awx + or + ansible.controller + +## Variables + +|Variable Name|Default Value|Required|Description|Example| +|`platform_state`|"present"|no|The state all objects will take unless overridden by object default|'absent'| +|`aap_hostname`|""|yes|URL to the Ansible Automation Platform Server.|127.0.0.1| +|`aap_validate_certs`|`True`|no|Whether or not to validate the Ansible Automation Platform Server's SSL certificate.|| +|`aap_username`|""|no|Admin User on the Ansible Automation Platform Server. Either username / password or oauthtoken need to be specified.|| +|`aap_password`|""|no|Platform Admin User's password on the Server. This should be stored in an Ansible Vault at vars/platform-secrets.yml or elsewhere and called from a parent playbook.|| +|`aap_token`|""|no|Controller Admin User's token on the Ansible Automation Platform Server. This should be stored in an Ansible Vault at or elsewhere and called from a parent playbook. Either username / password or oauthtoken need to be specified.|| +|`aap_request_timeout`|`10`|no|Specify the timeout in seconds Ansible should use in requests to the Ansible Automation Platform host.|| +|`controller_labels`|`see below`|yes|Data structure describing your label or labels Described below.|| + +### Secure Logging Variables + +The following Variables compliment each other. +If Both variables are not set, secure logging defaults to false. +The role defaults to False as normally the add labels task does not include sensitive information. +controller_configuration_labels_secure_logging defaults to the value of aap_configuration_secure_logging if it is not explicitly called. This allows for secure logging to be toggled for the entire suite of configuration roles with a single variable, or for the user to selectively use it. + +|Variable Name|Default Value|Required|Description| +|`controller_configuration_labels_secure_logging`|`False`|no|Whether or not to include the sensitive Label role tasks in the log. Set this value to `True` if you will be providing your sensitive values from elsewhere.| +|`aap_configuration_secure_logging`|`False`|no|This variable enables secure logging as well, but is shared across multiple roles, see above.| + +### Asynchronous Retry Variables + +The following Variables set asynchronous retries for the role. +If neither of the retries or delay or retries are set, they will default to their respective defaults. +This allows for all items to be created, then checked that the task finishes successfully. +This also speeds up the overall role. + +|Variable Name|Default Value|Required|Description| +|`aap_configuration_async_retries`|30|no|This variable sets the number of retries to attempt for the role globally.| +|`controller_configuration_labels_async_retries`|`{{ aap_configuration_async_retries }}`|no|This variable sets the number of retries to attempt for the role.| +|`aap_configuration_async_delay`|1|no|This sets the delay between retries for the role globally.| +|`controller_configuration_labels_async_delay`|`aap_configuration_async_delay`|no|This sets the delay between retries for the role.| +|`aap_configuration_loop_delay`|0|no|This sets the pause between each item in the loop for the roles globally. To help when API is getting overloaded.| +|`controller_configuration_labels_loop_delay`|`aap_configuration_loop_delay`|no|This sets the pause between each item in the loop for the role. To help when API is getting overloaded.| +|`aap_configuration_async_dir`|`null`|no|Sets the directory to write the results file for async tasks. The default value is set to `null` which uses the Ansible Default of `/root/.ansible_async/`.| + +## Data Structure + +### Labels Variables + +|Variable Name|Default Value|Required|type|Description| +|`name`|""|yes|str|Name of this label.| +|`new_name`|""|no|str|Setting this option will change the existing name (looked up via the name field).| +|`organization`|`False`|no|str|Organization this label belongs to.| +|`state`|`present`|no|str|Desired state of the resource.| + +### Standard Label Data Structure + +#### Json Example + +```json +{ + "controller_labels": [ + { + "name": "Dev", + "organization": "Satellite" + }, + { + "name": "Prod", + "organization": "Default" + } + ] +} + +``` + +#### Yaml Example + +```yaml +controller_labels: + - name: Dev + organization: Satellite + - name: Prod + organization: Default + +``` + +## Playbook Examples + +### Standard Role Usage + +```yaml +- name: Playbook to configure ansible controller post installation + hosts: localhost + connection: local + # Define following vars here, or in platform_configs/controller_auth.yml + # aap_hostname: ansible-controller-web-svc-test-project.example.com + # aap_username: admin + # aap_password: changeme + pre_tasks: + - name: Include vars from platform_configs directory + ansible.builtin.include_vars: + dir: ./yaml + ignore_files: [controller_config.yml.template] + extensions: ["yml"] + roles: + - {role: infra.aap_configuration.labels, when: controller_labels is defined} +``` + +## License + +[GPL-3.0](https://github.com/redhat-cop/aap_configuration#licensing) + +## Author + +[Sean Sullivan](https://github.com/sean-m-sullivan) diff --git a/collections/controller_configuration/controller_license.md b/collections/controller_configuration/controller_license.md new file mode 100644 index 0000000..6a7ba75 --- /dev/null +++ b/collections/controller_configuration/controller_license.md @@ -0,0 +1,151 @@ +--- +layout: default +title: controller_license +parent: infra.controller_configuration +--- + +# controller_configuration.license + +## Description + +An Ansible Role to deploy a license on Ansible Controller. + +This will either accept a manifest file, or use redhat subscription account credentials to lookup available subscriptions and use them. + +## Requirements + +ansible-galaxy collection install -r tests/collections/requirements.yml to be installed +Currently: + awx.awx + or + ansible.controller + +## Variables + +|Variable Name|Default Value|Required|Description|Example| +|`platform_state`|"present"|no|The state all objects will take unless overridden by object default|'absent'| +|`aap_hostname`|""|yes|URL to the Ansible Automation Platform Server.|127.0.0.1| +|`aap_validate_certs`|`True`|no|Whether or not to validate the Ansible Automation Platform Server's SSL certificate.|| +|`aap_username`|""|no|Admin User on the Ansible Automation Platform Server. Either username / password or oauthtoken need to be specified.|| +|`aap_password`|""|no|Platform Admin User's password on the Server. This should be stored in an Ansible Vault at vars/platform-secrets.yml or elsewhere and called from a parent playbook.|| +|`aap_token`|""|no|Controller Admin User's token on the Ansible Automation Platform Server. This should be stored in an Ansible Vault at or elsewhere and called from a parent playbook. Either username / password or oauthtoken need to be specified.|| +|`aap_request_timeout`|`10`|no|Specify the timeout in seconds Ansible should use in requests to the Ansible Automation Platform host.|| +|`controller_license`|`see below`|yes|Data structure describing your license for controller, described below.|| +|`redhat_subscription_username`|""|no|Red Hat or Red Hat Satellite username to get available subscriptions. Used only for Subscription lookup implementation.|| +|`redhat_subscription_password`|""|no|Red Hat or Red Hat Satellite password to get available subscriptions. Used only for Subscription lookup implementation.|| + +### Secure Logging Variables + +The following Variables compliment each other. +If Both variables are not set, secure logging defaults to false. +The role defaults to False as normally the add license task does not include sensitive information. +controller_configuration_license_secure_logging defaults to the value of aap_configuration_secure_logging if it is not explicitly called. This allows for secure logging to be toggled for the entire suite of controller configuration roles with a single variable, or for the user to selectively use it. + +|Variable Name|Default Value|Required|Description| +|`controller_configuration_license_secure_logging`|`False`|no|Whether or not to include the sensitive license role tasks in the log. Set this value to `True` if you will be providing your sensitive values from elsewhere.| +|`aap_configuration_secure_logging`|`False`|no|This variable enables secure logging as well, but is shared across multiple roles, see above.| + +## Data Structure + +### Manifest vs Subscription + +The module and this role can use either a manifest file, or lookup the subscription on your account. Only one method is needed, provide the appropriate variables to use the either method. + +### License Variables for using mainfest + +|Variable Name|Default Value|Required|Type|Description| +|`manifest_file`|""|no|obj|File path to a Red Hat subscription manifest (a .zip file)| +|`manifest_url`|""|no|obj|URL containing a Red Hat subscription manifest (a .zip file)| +|`manifest_content`|""|no|obj|Base64 encoded content of Red Hat subscription manifest| +|`manifest`|""|no|obj|DEPRECATED - changed to `manifest_file` (still works as an alias)| +|`manifest_username`|""|no|obj|Optional username for access to `manifest_url`| +|`manifest_password`|""|no|obj|Optional password for access to `manifest_url`| +|`pool_id`|""|no|str|Red Hat or Red Hat Satellite pool_id to attach to| +|`eula_accepted`|""|yes|bool|DEPRECATED since Tower 3.8 - Whether to accept the End User License Agreement for Ansible controller| +|`force`|`False`|no|bool|By default, the license manifest will only be applied if controller is currently unlicensed or trial licensed. When force=true, the license is always applied.| +|`state`|`present`|no|str|Desired state of the resource.| + +### License Variables for using Red Hat Subscription + +|Variable Name|Default Value|Required|Type|Description| +|`filters`|"default values"|no|str|dict of filters to use to narrow the subscription. See example below for how to use this.| +|`support_level`|"Self-Support"|no|str|DEPRECATED - changed to `manifest_file` (still works as an alias)| +|`list_num`|0|no|int|List index of the subscription to use, if you want to overide the default, it is recomended to use the filters to limit the pools found.| +|`pool_id`|""|no|str|Red Hat or Red Hat Satellite pool_id to attach to.| +|`force`|`False`|no|bool|By default, the license will only be applied if controller is currently unlicensed or trial licensed. When force=true, the license is always applied.| +|`use_lookup`|`False`|no|bool|Whether or not to lookup subscriptions.| +|`state`|`present`|no|str|Desired state of the resource.| + +### Standard License Data Structure + +#### Json Example + +```json +{ + "controller_license": { + "manifest_file": "/tmp/my_controller.license", + "force": true + } +} +``` + +#### Yaml Example + +```yaml +controller_license: + manifest_url: "https://fileserver.internal/controller_license.zip" + manifest_username: admin + manifest_password: password + force: false +``` + +## Playbook Examples + +### Standard Manifest Role Usage + +```yaml +- name: Playbook to configure ansible controller post installation + hosts: localhost + connection: local + # Define following vars here, or in platform_configs/controller_auth.yml + # aap_hostname: ansible-controller-web-svc-test-project.example.com + # aap_username: admin + # aap_password: changeme + pre_tasks: + - name: Include vars from platform_configs directory + ansible.builtin.include_vars: + dir: ./yaml + ignore_files: [controller_config.yml.template] + extensions: ["yml"] + roles: + - {role: infra.aap_configuration.license, when: controller_license is defined} +``` + +### Standard Subscription lookup Role Usage + +```yaml +- name: Playbook to configure ansible controller post installation + hosts: localhost + connection: local + vars: + aap_validate_certs: false + aap_hostname: controller.example.com + aap_username: admin + aap_password: changeme + redhat_subscription_username: changeme + redhat_subscription_password: changeme + controller_license: + filters: + product_name: "Red Hat Ansible Automation Platform" + support_level: "Self-Support" + roles: + - {role: infra.aap_configuration.license} +``` + +## License + +[GPL-3.0](https://github.com/redhat-cop/aap_configuration#licensing) + +## Author + +[Tom Page](https://github.com/Tompage1994) diff --git a/collections/controller_configuration/controller_notification_templates.md b/collections/controller_configuration/controller_notification_templates.md new file mode 100644 index 0000000..d65453a --- /dev/null +++ b/collections/controller_configuration/controller_notification_templates.md @@ -0,0 +1,203 @@ +--- +layout: default +title: controller_notification_templates +parent: infra.controller_configuration +--- + +# controller_configuration.notification_templates + +## Description + +An Ansible Role to add/update/remove notification templates on Ansible Controller. + +## Requirements + +ansible-galaxy collection install -r tests/collections/requirements.yml to be installed +Currently: + awx.awx + or + ansible.controller + +## Variables + +|Variable Name|Default Value|Required|Description|Example| +|`platform_state`|"present"|no|The state all objects will take unless overridden by object default|'absent'| +|`aap_hostname`|""|yes|URL to the Ansible Automation Platform Server.|127.0.0.1| +|`aap_validate_certs`|`True`|no|Whether or not to validate the Ansible Automation Platform Server's SSL certificate.|| +|`aap_username`|""|no|Admin User on the Ansible Automation Platform Server. Either username / password or oauthtoken need to be specified.|| +|`aap_password`|""|no|Platform Admin User's password on the Server. This should be stored in an Ansible Vault at vars/platform-secrets.yml or elsewhere and called from a parent playbook.|| +|`aap_token`|""|no|Controller Admin User's token on the Ansible Automation Platform Server. This should be stored in an Ansible Vault at or elsewhere and called from a parent playbook. Either username / password or oauthtoken need to be specified.|| +|`aap_request_timeout`|`10`|no|Specify the timeout in seconds Ansible should use in requests to the Ansible Automation Platform host.|| +|`controller_notifications`|`see below`|yes|Data structure describing your notification entries described below. Alias: notification_templates || + +### Enforcing defaults + +The following Variables compliment each other. +If Both variables are not set, enforcing default values is not done. +Enabling these variables enforce default values on options that are optional in the controller API. +This should be enabled to enforce configuration and prevent configuration drift. It is recomended to be enabled, however it is not enforced by default. + +Enabling this will enforce configurtion without specifying every option in the configuration files. + +'controller_configuration_notifications_enforce_defaults' defaults to the value of 'aap_configuration_enforce_defaults' if it is not explicitly called. This allows for enforced defaults to be toggled for the entire suite of controller configuration roles with a single variable, or for the user to selectively use it. + +|Variable Name|Default Value|Required|Description| +|`controller_configuration_notifications_enforce_defaults`|`False`|no|Whether or not to enforce default option values on only the applications role| +|`aap_configuration_enforce_defaults`|`False`|no|This variable enables enforced default values as well, but is shared across multiple roles, see above.| + +### Secure Logging Variables + +The following Variables compliment each other. +If Both variables are not set, secure logging defaults to false. +The role defaults to False as normally the add notification task does not include sensitive information. +`controller_configuration_notification_secure_logging` defaults to the value of `aap_configuration_secure_logging` if it is not explicitly called. This allows for secure logging to be toggled for the entire suite of configuration roles with a single variable, or for the user to selectively use it. + +|Variable Name|Default Value|Required|Description| +|`controller_configuration_notification_secure_logging`|`False`|no|Whether or not to include the sensitive notification role tasks in the log. Set this value to `True` if you will be providing your sensitive values from elsewhere.| +|`aap_configuration_secure_logging`|`False`|no|This variable enables secure logging as well, but is shared across multiple roles, see above.| + +### Asynchronous Retry Variables + +The following Variables set asynchronous retries for the role. +If neither of the retries or delay or retries are set, they will default to their respective defaults. +This allows for all items to be created, then checked that the task finishes successfully. +This also speeds up the overall role. + +|Variable Name|Default Value|Required|Description| +|`aap_configuration_async_retries`|30|no|This variable sets the number of retries to attempt for the role globally.| +|`controller_configuration_notification_async_retries`|`{{ aap_configuration_async_retries }}`|no|This variable sets the number of retries to attempt for the role.| +|`aap_configuration_async_delay`|1|no|This sets the delay between retries for the role globally.| +|`controller_configuration_notification_async_delay`|`aap_configuration_async_delay`|no|This sets the delay between retries for the role.| +|`aap_configuration_loop_delay`|0|no|This sets the pause between each item in the loop for the roles globally. To help when API is getting overloaded.| +|`controller_configuration_notifications_loop_delay`|`aap_configuration_loop_delay`|no|This sets the pause between each item in the loop for the role. To help when API is getting overloaded.| +|`aap_configuration_async_dir`|`null`|no|Sets the directory to write the results file for async tasks. The default value is set to `null` which uses the Ansible Default of `/root/.ansible_async/`.| + +## Data Structure + +### Notification Variables + +|Variable Name|Default Value|Required|Type|Description| +|`name`|""|yes|str|The name of the notification.| +|`new_name`|""|yes|str|Setting this option will change the existing name (looked up via the name field).| +|`copy_from`|""|no|str|Name or id to copy the Notification template from. This will copy an existing notification and change any parameters supplied.| +|`description`|""|no|str|The description of the notification.| +|`organization`|""|no|str|The organization applicable to the notification.| +|`notification_type`|""|no|str|The type of notification to be sent.| +|`notification_configuration`|""|no|str|The notification configuration file. Note providing this field would disable all depreciated notification-configuration-related fields.| +|`messages`|""|no|list|Optional custom messages for notification template. Assumes any instance of two space __ are used for adding variables and removes them. Does not effect single space.| +|`state`|`present`|no|str|Desired state of the resource.| + +### Standard Notification Data Structure + +#### Json Example + +```json +{ + "controller_notifications": [ + { + "name": "irc-satqe-chat-notification", + "description": "Notify us on job in IRC!", + "organization": "Satellite", + "notification_type": "irc", + "notification_configuration": { + "use_tls": false, + "use_ssl": false, + "password": "", + "port": 6667, + "server": "irc.freenode.com", + "nickname": "Ansible-controller-Stage-Bot-01", + "targets": [ + "#my-channel" + ] + } + }, + { + "name": "Email notification", + "description": "Send out emails for controller jobs", + "organization": "Satellite", + "notification_type": "email", + "notification_configuration": { + "username": "", + "sender": "controller0@example.com", + "recipients": [ + "admin@example.com" + ], + "use_tls": false, + "host": "smtp.example.com", + "use_ssl": false, + "password": "", + "port": 25 + } + } + ] +} +``` + +#### Yaml Example + +```yaml +controller_notifications: + - name: irc-satqe-chat-notification + description: Notify us on job in IRC! + organization: Satellite + notification_type: irc + notification_configuration: + use_tls: false + use_ssl: false + password: '' # this is required even if there's no password + port: 6667 + server: irc.freenode.com + nickname: Ansible-controller-Stage-Bot-01 + targets: + - "#my-channel" + messages: + success: + body: '{"fields": {"project": {"id": "11111"},"summary": "Lab { { job.status + }} Ansible controller { { job.name }}","description": "{ { job.status }} in { { + job.name }} { { job.id }} { {url}}","issuetype": {"id": "1"}}}' + - name: Email notification + description: Send out emails for controller jobs + organization: Satellite + notification_type: email + notification_configuration: + username: '' # this is required even if there's no username + sender: controller0@example.com + recipients: + - admin@example.com + use_tls: false + host: smtp.example.com + use_ssl: false + password: '' # this is required even if there's no password + port: 25 +``` + +## Playbook Examples + +### Standard Role Usage + +```yaml +- name: Playbook to configure ansible controller post installation + hosts: localhost + connection: local + # Define following vars here, or in platform_configs/controller_auth.yml + # aap_hostname: ansible-controller-web-svc-test-project.example.com + # aap_username: admin + # aap_password: changeme + pre_tasks: + - name: Include vars from platform_configs directory + ansible.builtin.include_vars: + dir: ./yaml + ignore_files: [controller_config.yml.template] + extensions: ["yml"] + roles: + - {role: infra.aap_configuration.notification_templates, when: controller_notifications is defined} +``` + +## License + +[GPL-3.0](https://github.com/redhat-cop/aap_configuration#licensing) + +## Author + +[Tom Page](https://github.com/Tompage1994) +[Sean Sullivan](https://github.com/sean-m-sullivan) diff --git a/collections/controller_configuration/controller_organizations.md b/collections/controller_configuration/controller_organizations.md new file mode 100644 index 0000000..0879f65 --- /dev/null +++ b/collections/controller_configuration/controller_organizations.md @@ -0,0 +1,194 @@ +--- +layout: default +title: controller_organizations +parent: infra.controller_configuration +--- + +# controller_configuration.organizations + +## Description + +An Ansible Role to create/update/remove Organizations on Ansible Controller. + +## Requirements + +ansible-galaxy collection install -r tests/collections/requirements.yml to be installed +Currently: + awx.awx + or + ansible.controller + +## Variables + +|Variable Name|Default Value|Required|Description|Example| +|`platform_state`|"present"|no|The state all objects will take unless overridden by object default|'absent'| +|`aap_hostname`|""|yes|URL to the Ansible Automation Platform Server.|127.0.0.1| +|`aap_validate_certs`|`True`|no|Whether or not to validate the Ansible Automation Platform Server's SSL certificate.|| +|`aap_username`|""|no|Admin User on the Ansible Automation Platform Server. Either username / password or oauthtoken need to be specified.|| +|`aap_password`|""|no|Platform Admin User's password on the Server. This should be stored in an Ansible Vault at vars/platform-secrets.yml or elsewhere and called from a parent playbook.|| +|`aap_token`|""|no|Controller Admin User's token on the Ansible Automation Platform Server. This should be stored in an Ansible Vault at or elsewhere and called from a parent playbook. Either username / password or oauthtoken need to be specified.|| +|`aap_request_timeout`|`10`|no|Specify the timeout in seconds Ansible should use in requests to the Ansible Automation Platform host.|| +|`aap_organizations`|`see below`|yes|Data structure describing your organization or organizations Described below. Alias: organizations || +|`assign_galaxy_credentials_to_org`|`true`|no|Boolean to indicate whether credentials should be assigned or not. It should be noted that credentials must exist before adding it. The dispatch role will set this to `false`, before re-running the role with it set to `true`. || +|`assign_default_ee_to_org`|`true`|no|Boolean to indicate whether default execution environment should be assigned or not. It should be noted that execution environment must exist before adding it. The dispatch role will set this to `false`, before re-running the role with it set to `true`. || +|`assign_notification_templates_to_org`|`true`|no|Boolean to indicate whether notification templates should be assigned or not. It should be noted that the templates must exist before adding them. The dispatch role will set this to `false`, before re-running the role with it set to `true`. || +|`assign_instance_groups_to_org`|`true`|no|Boolean to indicate whether an instance group should be assigned or not. It should be noted that the instance group must exist before adding it. || + +### Enforcing defaults + +The following Variables compliment each other. +If Both variables are not set, enforcing default values is not done. +Enabling these variables enforce default values on options that are optional in the controller API. +This should be enabled to enforce configuration and prevent configuration drift. It is recomended to be enabled, however it is not enforced by default. + +Enabling this will enforce configurtion without specifying every option in the configuration files. + +'controller_configuration_organizations_enforce_defaults' defaults to the value of 'aap_configuration_enforce_defaults' if it is not explicitly called. This allows for enforced defaults to be toggled for the entire suite of controller configuration roles with a single variable, or for the user to selectively use it. + +|Variable Name|Default Value|Required|Description| +|`controller_configuration_organizations_enforce_defaults`|`False`|no|Whether or not to enforce default option values on only the applications role| +|`aap_configuration_enforce_defaults`|`False`|no|This variable enables enforced default values as well, but is shared across multiple roles, see above.| + +### Secure Logging Variables + +The following Variables compliment each other. +If Both variables are not set, secure logging defaults to false. +The role defaults to False as normally the add organization task does not include sensitive information. +controller_configuration_organizations_secure_logging defaults to the value of aap_configuration_secure_logging if it is not explicitly called. This allows for secure logging to be toggled for the entire suite of configuration roles with a single variable, or for the user to selectively use it. + +|Variable Name|Default Value|Required|Description| +|`controller_configuration_organizations_secure_logging`|`False`|no|Whether or not to include the sensitive Organization role tasks in the log. Set this value to `True` if you will be providing your sensitive values from elsewhere.| +|`aap_configuration_secure_logging`|`False`|no|This variable enables secure logging as well, but is shared across multiple roles, see above.| + +### Asynchronous Retry Variables + +The following Variables set asynchronous retries for the role. +If neither of the retries or delay or retries are set, they will default to their respective defaults. +This allows for all items to be created, then checked that the task finishes successfully. +This also speeds up the overall role. + +|Variable Name|Default Value|Required|Description| +|`aap_configuration_async_retries`|30|no|This variable sets the number of retries to attempt for the role globally.| +|`controller_configuration_organizations_async_retries`|`{{ aap_configuration_async_retries }}`|no|This variable sets the number of retries to attempt for the role.| +|`aap_configuration_async_delay`|1|no|This sets the delay between retries for the role globally.| +|`controller_configuration_organizations_async_delay`|`aap_configuration_async_delay`|no|This sets the delay between retries for the role.| +|`aap_configuration_loop_delay`|0|no|This sets the pause between each item in the loop for the roles globally. To help when API is getting overloaded.| +|`controller_configuration_organizations_loop_delay`|`aap_configuration_loop_delay`|no|This sets the pause between each item in the loop for the role. To help when API is getting overloaded.| +|`aap_configuration_async_dir`|`null`|no|Sets the directory to write the results file for async tasks. The default value is set to `null` which uses the Ansible Default of `/root/.ansible_async/`.| + +## Organization Data Structure + +This role accepts two data models. A simple straightforward easy to maintain model, and another based on the controller api. The 2nd one is more complicated and includes more detail, and is compatible with controller import/export. + +### Organization Variables + +|Variable Name|Default Value|Required|Type|Description| +|`name`|""|yes|str|Name of Organization| +|`new_name`|""|no|str|New name of Organization| +|`description`|`False`|no|str|Description of of Organization.| +|`custom_virtualenv`|""|no|str|Local absolute file path containing a custom Python virtualenv to use.| +|`max_hosts`|""|no|int|The max hosts allowed in this organization.| +|`instance_groups`|""|no|list|list of Instance Groups for this Organization to run on.| +|`galaxy_credentials`|""|no|list|The credentials to use with private automationhub.| +|`default_environment`|""|no|str|Default Execution Environment to use for jobs owned by the Organization.| +|`notification_templates_started`|""|no|list|The notifications on started to use for this organization in a list.| +|`notification_templates_success`|""|no|list|The notifications on success to use for this organization in a list.| +|`notification_templates_error`|""|no|list|The notifications on error to use for this organization in a list.| +|`notification_templates_approvals`|""|no|list|The notifications for approval to use for this organization in a list.| +|`state`|`present`|no|str|Desired state of the resource.| + +### Standard Organization Data Structure model + +#### Json Example + +```json +{ + "aap_organizations": [ + { + "name": "Default", + "description": "This is the Default Group" + }, + { + "name": "Automation Group", + "description": "This is the Automation Group", + "custom_virtualenv": "/opt/cust/environment/", + "max_hosts": 10, + "galaxy_credentials": "Automation Hub", + "notification_templates_error": [ + "Slack_for_testing" + ] + } + ] +} +``` + +#### Yaml Example + +```yaml +aap_organizations: +- name: Default + description: This is the Default Group +- name: Automation Group + description: This is the Automation Group + custom_virtualenv: "/opt/cust/environment/" + max_hosts: 10 +``` + +#### Controller Export Data structure model + +##### Export Yaml Example + +```yaml +aap_organizations: +- name: Satellite + description: Satellite + max_hosts: 0 + custom_virtualenv: + related: + notification_templates_started: [] + notification_templates_success: [] + notification_templates_error: + - name: irc-satqe-chat-notification + notification_templates_approvals: [] +- name: Default + description: Default + max_hosts: 0 + custom_virtualenv: + galaxy_credentials: + - Automation Hub + related: + notification_templates_started: [] + notification_templates_success: [] + notification_templates_error: [] + notification_templates_approvals: [] +``` + +## Playbook Examples + +### Standard Role Usage + +```yaml +- name: Playbook to configure ansible controller post installation + hosts: localhost + connection: local + # Define following vars here, or in platform_configs/controller_auth.yml + # aap_hostname: ansible-controller-web-svc-test-project.example.com + # aap_username: admin + # aap_password: changeme + pre_tasks: + - name: Include vars from platform_configs directory + ansible.builtin.include_vars: + dir: ./yaml + ignore_files: [controller_config.yml.template] + extensions: ["yml"] + roles: + - {role: infra.aap_configuration.organizations, when: aap_organizations is defined} +``` + +## License + +[GPL-3.0](https://github.com/redhat-cop/aap_configuration#licensing) + +## Author + +[Sean Sullivan](https://github.com/sean-m-sullivan) diff --git a/collections/controller_configuration/controller_project_update.md b/collections/controller_configuration/controller_project_update.md new file mode 100644 index 0000000..0f745b7 --- /dev/null +++ b/collections/controller_configuration/controller_project_update.md @@ -0,0 +1,130 @@ +--- +layout: default +title: controller_project_update +parent: infra.controller_configuration +--- + +# controller_configuration.project_update + +## Description + +An Ansible Role to update a list of projects on Ansible Controller. + +## Requirements + +ansible-galaxy collection install -r tests/collections/requirements.yml to be installed +Currently: + awx.awx + or + ansible.controller + +## Variables + +|Variable Name|Default Value|Required|Description|Example| +|`platform_state`|"present"|no|The state all objects will take unless overridden by object default|'absent'| +|`aap_hostname`|""|yes|URL to the Ansible Automation Platform Server.|127.0.0.1| +|`aap_validate_certs`|`True`|no|Whether or not to validate the Ansible Automation Platform Server's SSL certificate.|| +|`aap_username`|""|no|Admin User on the Ansible Automation Platform Server. Either username / password or oauthtoken need to be specified.|| +|`aap_password`|""|no|Platform Admin User's password on the Server. This should be stored in an Ansible Vault at vars/platform-secrets.yml or elsewhere and called from a parent playbook.|| +|`aap_token`|""|no|Controller Admin User's token on the Ansible Automation Platform Server. This should be stored in an Ansible Vault at or elsewhere and called from a parent playbook. Either username / password or oauthtoken need to be specified.|| +|`aap_request_timeout`|`10`|no|Specify the timeout in seconds Ansible should use in requests to the Ansible Automation Platform host.|| +|`controller_projects`|`see below`|yes|Data structure describing the project to update Described below. Alias: projects || + +### Secure Logging Variables + +The following Variables compliment each other. +If Both variables are not set, secure logging defaults to false. +The role defaults to False as normally the project update task does not include sensitive information. +controller_configuration_project_update_secure_logging defaults to the value of aap_configuration_secure_logging if it is not explicitly called. This allows for secure logging to be toggled for the entire suite of configuration roles with a single variable, or for the user to selectively use it. + +|Variable Name|Default Value|Required|Description| +|`controller_configuration_project_update_secure_logging`|`False`|no|Whether or not to include the sensitive Project role tasks in the log. Set this value to `True` if you will be providing your sensitive values from elsewhere.| +|`aap_configuration_secure_logging`|`False`|no|This variable enables secure logging as well, but is shared across multiple roles, see above.| + +### Asynchronous Retry Variables + +The following Variables set asynchronous retries for the role. +If neither of the retries or delay or retries are set, they will default to their respective defaults. +This allows for all items to be created, then checked that the task finishes successfully. +This also speeds up the overall role. + +|Variable Name|Default Value|Required|Description| +|`aap_configuration_async_retries`|60|no|This variable sets the number of retries to attempt for the role globally.| +|`controller_configuration_project_update_async_retries`|60|no|This variable sets the number of retries to attempt for the role.| +|`aap_configuration_async_delay`|10|no|This sets the delay between retries for the role globally.| +|`controller_configuration_project_update_async_delay`|10|no|This sets the delay between retries for the role.| +|`aap_configuration_loop_delay`|0|no|This sets the pause between each item in the loop for the roles globally. To help when API is getting overloaded.| +|`controller_configuration_project_update_loop_delay`|`aap_configuration_loop_delay`|no|This sets the pause between each item in the loop for the role. To help when API is getting overloaded.| +|`aap_configuration_async_dir`|`null`|no|Sets the directory to write the results file for async tasks. The default value is set to `null` which uses the Ansible Default of `/root/.ansible_async/`.| + +## Data Structure + +### Project Update Variables + +|Variable Name|Default Value|Required|Type|Description| +|`name`|""|yes|str|The name or id of the project to update.| +|`organization`|""|no|str|Organization the project exists in. Used for lookup only.| +|`wait`|""|no|str|Wait for the project to complete.| +|`interval`|`controller_configuration_project_update_async_delay`|no|str|The interval to request an update from controller.| +|`timeout`|""|no|str|If waiting for the job to complete this will abort after this amount of seconds.| +|`update_project`|`False`|no|bool|If defined and true, the project update will be executed, otherwise it won't.| + +### Standard Project Update Data Structure + +#### Yaml Example + +```yaml +controller_projects: + - name: Test Project + scm_type: git + scm_url: https://github.com/ansible/tower-example.git + scm_branch: master + scm_clean: true + description: Test Project 1 + organization: Satellite + wait: true + - name: Test Project 2 + scm_type: git + scm_url: https://github.com/ansible/tower-example.git + description: Test Project 2 + organization: Satellite + wait: true + - name: Test Inventory source project + scm_type: git + scm_url: https://github.com/ansible/ansible-examples.git + description: ansible-examples + organization: Satellite + wait: true + +``` + +## Playbook Examples + +### Standard Role Usage + +```yaml +- name: Playbook to configure ansible controller post installation + hosts: localhost + connection: local + # Define following vars here, or in platform_configs/controller_auth.yml + # aap_hostname: ansible-controller-web-svc-test-project.example.com + # aap_username: admin + # aap_password: changeme + pre_tasks: + - name: Include vars from platform_configs directory + ansible.builtin.include_vars: + dir: ./yaml + ignore_files: [controller_config.yml.template] + extensions: ["yml"] + roles: + - {role: infra.aap_configuration.project_update, when: controller_projects is defined} + +``` + +## License + +[GPL-3.0](https://github.com/redhat-cop/aap_configuration#licensing) + +## Author + +[Sean Sullivan](https://github.com/sean-m-sullivan) diff --git a/collections/controller_configuration/controller_projects.md b/collections/controller_configuration/controller_projects.md new file mode 100644 index 0000000..7295ef3 --- /dev/null +++ b/collections/controller_configuration/controller_projects.md @@ -0,0 +1,179 @@ +--- +layout: default +title: controller_projects +parent: infra.controller_configuration +--- + +# controller_configuration.projects + +## Description + +An Ansible Role to create/update/remove Projects on Ansible Controller. + +## Requirements + +ansible-galaxy collection install -r tests/collections/requirements.yml to be installed +Currently: + awx.awx + or + ansible.controller + +## Variables + +|Variable Name|Default Value|Required|Type|Description|Example| +|`controller_state`|"present"|no|str|The state all objects will take unless overridden by object default|'absent'| +|`aap_hostname`|""|yes|str|URL to the Ansible Controller Server.|127.0.0.1| +|`aap_validate_certs`|`True`|no|str|Whether or not to validate the Ansible Controller Server's SSL certificate.|| +|`aap_username`|""|no|str|Admin User on the Ansible Controller Server. Either username / password or oauthtoken need to be specified.|| +|`aap_password`|""|no|str|Controller Admin User's password on the Ansible Controller Server. This should be stored in an Ansible Vault at vars/controller-secrets.yml or elsewhere and called from a parent playbook. Either username / password or oauthtoken need to be specified.|| +|`controller_oauthtoken`|""|no|str|Controller Admin User's token on the Ansible Controller Server. This should be stored in an Ansible Vault at or elsewhere and called from a parent playbook. Either username / password or oauthtoken need to be specified.|| +|`controller_request_timeout`|`10`|no|int|Specify the timeout in seconds Ansible should use in requests to the Ansible Automation Platform host.|| +|`controller_projects`|`see below`|yes|str|Data structure describing your project or projects Described below. Alias: projects || + +### Enforcing defaults + +The following Variables compliment each other. +If Both variables are not set, enforcing default values is not done. +Enabling these variables enforce default values on options that are optional in the controller API. +This should be enabled to enforce configuration and prevent configuration drift. It is recomended to be enabled, however it is not enforced by default. + +Enabling this will enforce configurtion without specifying every option in the configuration files. + +'controller_configuration_projects_enforce_defaults' defaults to the value of 'aap_configuration_enforce_defaults' if it is not explicitly called. This allows for enforced defaults to be toggled for the entire suite of controller configuration roles with a single variable, or for the user to selectively use it. + +|Variable Name|Default Value|Required|Description| +|`controller_configuration_projects_enforce_defaults`|`False`|no|Whether or not to enforce default option values on only the applications role| +|`aap_configuration_enforce_defaults`|`False`|no|This variable enables enforced default values as well, but is shared across multiple roles, see above.| + +### Secure Logging Variables + +The following Variables compliment each other. +If Both variables are not set, secure logging defaults to false. +The role defaults to False as normally the add projects task does not include sensitive information. +controller_configuration_projects_secure_logging defaults to the value of aap_configuration_secure_logging if it is not explicitly called. This allows for secure logging to be toggled for the entire suite of configuration roles with a single variable, or for the user to selectively use it. + +|Variable Name|Default Value|Required|Type|Description| +|`controller_configuration_projects_secure_logging`|`False`|no|str|Whether or not to include the sensitive Project role tasks in the log. Set this value to `True` if you will be providing your sensitive values from elsewhere.| +|`aap_configuration_secure_logging`|`False`|no|str|This variable enables secure logging as well, but is shared across multiple roles, see above.| + +### Asynchronous Retry Variables + +The following Variables set asynchronous retries for the role. +If neither of the retries or delay or retries are set, they will default to their respective defaults. +This allows for all items to be created, then checked that the task finishes successfully. +This also speeds up the overall role. + +|Variable Name|Default Value|Required|Type|Description| +|`aap_configuration_async_retries`|30|no|str|This variable sets the number of retries to attempt for the role globally.| +|`controller_configuration_projects_async_retries`|`{{ aap_configuration_async_retries }}`|no|str|This variable sets the number of retries to attempt for the role.| +|`aap_configuration_async_delay`|1|no|str|This sets the delay between retries for the role globally.| +|`controller_configuration_projects_async_delay`|`aap_configuration_async_delay`|no|str|This sets the delay between retries for the role.| +|`aap_configuration_loop_delay`|0|no|int|This sets the pause between each item in the loop for the roles globally. To help when API is getting overloaded.| +|`controller_configuration_projects_loop_delay`|`aap_configuration_loop_delay`|no|int|This sets the pause between each item in the loop for the role. To help when API is getting overloaded.| +|`aap_configuration_async_dir`|`null`|no|bool|Sets the directory to write the results file for async tasks. The default value is set to `null` which uses the Ansible Default of `/root/.ansible_async/`.| + +## Data Structure + +### Project Variables + +|Variable Name|Default Value|Required|Type|Description| +|`name`|""|yes|str|Name of Project| +|`new_name`|""|no|str|Setting this option will change the existing name (looked up via the name field).| +|`copy_from`|""|no|str|Name or id to copy the project from. This will copy an existing project and change any parameters supplied.| +|`description`|`False`|no|str|Description of the Project.| +|`organization`|`False`|yes|str|Name of organization for project.| +|`scm_type`|""|no|str|Type of SCM resource.| +|`scm_url`|""|no|str|URL of SCM resource.| +|`default_environment`|""|no|str|Default Execution Environment to use for jobs relating to the project.| +|`local_path`|""|no|str|The server playbook directory for manual projects.| +|`scm_branch`|""|no|str|The branch to use for the SCM resource.| +|`scm_refspec`|""|no|str|The refspec to use for the SCM resource.| +|`credential`|""|no|str|Name of the credential to use with this SCM resource.| +|`signature_validation_credential`|""|no|str|Name of the credential to use for signature validation. If signature validation credential is provided, signature validation will be enabled.| +|`scm_clean`|""|no|bool|Remove local modifications before updating.| +|`scm_delete_on_update`|""|no|bool|Remove the repository completely before updating.| +|`scm_track_submodules`|""|no|bool|Track submodules latest commit on specified branch.| +|`scm_update_on_launch`|""|no|bool|Before an update to the local repository before launching a job with this project.| +|`scm_update_cache_timeout`|""|no|str|Cache Timeout to cache prior project syncs for a certain number of seconds. Only valid if scm_update_on_launch is to True, otherwise ignored.| +|`allow_override`|""|no|str|Allow changing the SCM branch or revision in a job template that uses this project.| +|`timeout`|""|no|int|The amount of time (in seconds) to run before the SCM Update is canceled. A value of 0 means no timeout.| +|`custom_virtualenv`|""|no|str|Local absolute file path containing a custom Python virtualenv to use.| +|`notification_templates_started`|""|no|list|The notifications on started to use for this organization in a list.| +|`notification_templates_success`|""|no|list|The notifications on success to use for this organization in a list.| +|`notification_templates_error`|""|no|list|The notifications on error to use for this organization in a list.| +|`state`|`present`|no|str|Desired state of the resource.| +|`wait`|""|no|bool|Provides option to wait for completed project sync before returning.| +|`update_project`|`False`|no|bool|Force project to update after changes.Used in conjunction with wait, interval, and timeout.| +|`interval`|`controller_configuration_projects_async_delay`|no|float|The interval to request an update from controller. Requires wait.| + +### Standard Project Data Structure + +#### Json Example + +```json +{ + "controller_projects": [ + { + "name": "controller Config", + "organization": "Default", + "scm_branch": "master", + "scm_clean": "no", + "scm_delete_on_update": "no", + "scm_type": "git", + "scm_update_on_launch": "no", + "scm_url": "https://github.com/ansible/tower-example.git", + "notification_templates_error": [ + "Slack_for_testing" + ] + } + ] + } + +``` + +#### Yaml Example + +```yaml +controller_projects: +- name: controller Config + organization: Default + scm_branch: master + scm_clean: 'no' + scm_delete_on_update: 'no' + scm_type: git + scm_update_on_launch: 'no' + scm_url: https://github.com/ansible/tower-example.git + notification_templates_error: + - Slack_for_testing + +``` + +## Playbook Examples + +### Standard Role Usage + +```yaml +- name: Playbook to configure ansible controller post installation + hosts: localhost + connection: local + # Define following vars here, or in platform_configs/controller_auth.yml + # aap_hostname: ansible-controller-web-svc-test-project.example.com + # aap_username: admin + # aap_password: changeme + pre_tasks: + - name: Include vars from platform_configs directory + ansible.builtin.include_vars: + dir: ./yaml + ignore_files: [controller_config.yml.template] + extensions: ["yml"] + roles: + - {role: infra.aap_configuration.projects, when: controller_projects is defined} +``` + +## License + +[GPL-3.0](https://github.com/redhat-cop/aap_configuration#licensing) + +## Author + +[Sean Sullivan](https://github.com/sean-m-sullivan) diff --git a/collections/controller_configuration/controller_roles.md b/collections/controller_configuration/controller_roles.md new file mode 100644 index 0000000..d5fb25b --- /dev/null +++ b/collections/controller_configuration/controller_roles.md @@ -0,0 +1,196 @@ +--- +layout: default +title: controller_roles +parent: infra.controller_configuration +--- + +# controller_configuration.roles + +## Description + +An Ansible Role to create/update/remove RBAC Entries on Ansible Controller. + +## Requirements + +ansible-galaxy collection install -r tests/collections/requirements.yml to be installed +Currently: + awx.awx + or + ansible.controller + +## Variables + +|Variable Name|Default Value|Required|Description|Example| +|`platform_state`|"present"|no|The state all objects will take unless overridden by object default|'absent'| +|`aap_hostname`|""|yes|URL to the Ansible Automation Platform Server.|127.0.0.1| +|`aap_validate_certs`|`True`|no|Whether or not to validate the Ansible Automation Platform Server's SSL certificate.|| +|`aap_username`|""|no|Admin User on the Ansible Automation Platform Server. Either username / password or oauthtoken need to be specified.|| +|`aap_password`|""|no|Platform Admin User's password on the Server. This should be stored in an Ansible Vault at vars/platform-secrets.yml or elsewhere and called from a parent playbook.|| +|`aap_token`|""|no|Controller Admin User's token on the Ansible Automation Platform Server. This should be stored in an Ansible Vault at or elsewhere and called from a parent playbook. Either username / password or oauthtoken need to be specified.|| +|`aap_request_timeout`|`10`|no|Specify the timeout in seconds Ansible should use in requests to the Ansible Automation Platform host.|| +|`controller_roles`|`see below`|yes|Data structure describing your RBAC entries described below.|| + +### Enforcing defaults + +The following Variables compliment each other. +If Both variables are not set, enforcing default values is not done. +Enabling these variables enforce default values on options that are optional in the controller API. +This should be enabled to enforce configuration and prevent configuration drift. It is recomended to be enabled, however it is not enforced by default. + +Enabling this will enforce configurtion without specifying every option in the configuration files. + +'controller_configuration_role_enforce_defaults' defaults to the value of 'aap_configuration_enforce_defaults' if it is not explicitly called. This allows for enforced defaults to be toggled for the entire suite of controller configuration roles with a single variable, or for the user to selectively use it. + +|Variable Name|Default Value|Required|Description| +|`controller_configuration_role_enforce_defaults`|`False`|no|Whether or not to enforce default option values on only the applications role| +|`aap_configuration_enforce_defaults`|`False`|no|This variable enables enforced default values as well, but is shared across multiple roles, see above.| + +### Secure Logging Variables + +The following Variables compliment each other. +If Both variables are not set, secure logging defaults to false. +The role defaults to False as normally the add rbac task does not include sensitive information. +`controller_configuration_role_secure_logging` defaults to the value of `aap_configuration_secure_logging` if it is not explicitly called. This allows for secure logging to be toggled for the entire suite of configuration roles with a single variable, or for the user to selectively use it. + +|Variable Name|Default Value|Required|Description| +|`controller_configuration_role_secure_logging`|`False`|no|Whether or not to include the sensitive rbac role tasks in the log. Set this value to `True` if you will be providing your sensitive values from elsewhere.| +|`aap_configuration_secure_logging`|`False`|no|This variable enables secure logging as well, but is shared across multiple roles, see above.| + +### Asynchronous Retry Variables + +The following Variables set asynchronous retries for the role. +If neither of the retries or delay or retries are set, they will default to their respective defaults. +This allows for all items to be created, then checked that the task finishes successfully. +This also speeds up the overall role. + +|Variable Name|Default Value|Required|Description| +|`aap_configuration_async_retries`|30|no|This variable sets the number of retries to attempt for the role globally.| +|`controller_configuration_role_async_retries`|`{{ aap_configuration_async_retries }}`|no|This variable sets the number of retries to attempt for the role.| +|`aap_configuration_async_delay`|1|no|This sets the delay between retries for the role globally.| +|`controller_configuration_role_async_delay`|`aap_configuration_async_delay`|no|This sets the delay between retries for the role.| +|`aap_configuration_loop_delay`|0|no|This sets the pause between each item in the loop for the roles globally. To help when API is getting overloaded.| +|`controller_configuration_role_loop_delay`|`aap_configuration_loop_delay`|no|This sets the pause between each item in the loop for the role. To help when API is getting overloaded.| +|`aap_configuration_async_dir`|`null`|no|Sets the directory to write the results file for async tasks. The default value is set to `null` which uses the Ansible Default of `/root/.ansible_async/`.| + +## Data Structure + +### Role Variables + +|Variable Name|Default Value|Required|Type|Description| +|`user`|""|no|str|The user for which the role applies| +|`users`|""|no|list|The users for which the role applies| +|`team`|""|no|str|The team for which the role applies| +|`teams`|""|no|list|The teams for which the role applies| +|`roles`|""|no|str (see note below)|The roles which are applied to one of {`target_team`, `inventory`, `job_template`, `target_team`, `inventory`, `job_template`} for either `user` or `team` | +|`role`|""|no|str (see note below)|The role which is applied to one of {`target_team`, `inventory`, `job_template`, `target_team`, `inventory`, `job_template`} for either `user` or `team` | +|`target_team`|""|no|str|The team the role applies against| +|`target_teams`|""|no|list|The teams the role applies against| +|`inventory`|""|no|str|The inventory the role applies against| +|`inventories`|""|no|list|The inventories the role applies against| +|`job_template`|""|no|str|The job template the role applies against| +|`job_templates`|""|no|list|The job templates the role applies against| +|`workflow`|""|no|str|The workflow the role applies against| +|`workflows`|""|no|list|The workflows the role applies against| +|`credential`|""|no|str|The credential the role applies against| +|`credentials`|""|no|list|The credentials the role applies against| +|`organization`|""|no|str|The organization the role applies against| +|`organizations`|""|no|list|The organizations the role applies against| +|`lookup_organization`|""|no|str|Organization the inventories, job templates, projects, or workflows the items exists in. Used to help lookup the object, for organization roles see organization. If not provided, will lookup by name only, which does not work with duplicates.| +|`project`|""|no|str|The project the role applies against| +|`projects`|""|no|list|The project the role applies against| +|`instance_groups`|""|no|list|The instance groups the role applies against| +|`state`|`present`|no|str|Desired state of the resource.| + +#### Role + +`role` must be one of the following (or roles must contain a list made up from the following): + +- `admin` +- `read` +- `member` +- `execute` +- `adhoc` +- `update` +- `use` +- `approval` +- `auditor` +- `project_admin` +- `inventory_admin` +- `credential_admin` +- `workflow_admin` +- `notification_admin` +- `job_template_admin` +- `execution_environment_admin` + +Note that the `roles` option takes precedence over the `role` option and simply allows to specify multiple roles for a user or team (or set of users or teams). + +### Standard RBAC Data Structure + +#### Json Example + +```json +{ + "controller_roles": [ + { + "user": "jdoe", + "target_team": "My Team", + "role": "member" + }, + { + "team": "My Team", + "organization": "Default", + "roles": [ + "execute", + "read" + ] + } + ] +} +``` + +git check + +```yaml +controller_roles: +- user: jdoe + users: + - thing1 + - thing2 + target_team: "My Team" + role: member +- team: "My Team" + organization: "Default" + roles: + - execute + - read +``` + +## Playbook Examples + +### Standard Role Usage + +```yaml +- name: Playbook to configure ansible controller post installation + hosts: localhost + connection: local + # Define following vars here, or in platform_configs/controller_auth.yml + # aap_hostname: ansible-controller-web-svc-test-project.example.com + # aap_username: admin + # aap_password: changeme + pre_tasks: + - name: Include vars from platform_configs directory + ansible.builtin.include_vars: + dir: ./yaml + ignore_files: [controller_config.yml.template] + extensions: ["yml"] + roles: + - {role: infra.aap_configuration.roles, when: controller_roles is defined} +``` + +## License + +[GPL-3.0](https://github.com/redhat-cop/aap_configuration#licensing) + +## Author + +[Tom Page](https://github.com/Tompage1994) diff --git a/collections/controller_configuration/controller_schedules.md b/collections/controller_configuration/controller_schedules.md new file mode 100644 index 0000000..4d6f4ba --- /dev/null +++ b/collections/controller_configuration/controller_schedules.md @@ -0,0 +1,171 @@ +--- +layout: default +title: controller_schedules +parent: infra.controller_configuration +--- + +# controller_configuration.schedules + +## Description + +An Ansible Role to create/update/remove Schedules on Ansible Controller. + +## Requirements + +ansible-galaxy collection install -r tests/collections/requirements.yml to be installed +Currently: + awx.awx + or + ansible.controller + +## Variables + +|Variable Name|Default Value|Required|Description|Example| +|`platform_state`|"present"|no|The state all objects will take unless overridden by object default|'absent'| +|`aap_hostname`|""|yes|URL to the Ansible Automation Platform Server.|127.0.0.1| +|`aap_validate_certs`|`True`|no|Whether or not to validate the Ansible Automation Platform Server's SSL certificate.|| +|`aap_username`|""|no|Admin User on the Ansible Automation Platform Server. Either username / password or oauthtoken need to be specified.|| +|`aap_password`|""|no|Platform Admin User's password on the Server. This should be stored in an Ansible Vault at vars/platform-secrets.yml or elsewhere and called from a parent playbook.|| +|`aap_token`|""|no|Controller Admin User's token on the Ansible Automation Platform Server. This should be stored in an Ansible Vault at or elsewhere and called from a parent playbook. Either username / password or oauthtoken need to be specified.|| +|`aap_request_timeout`|`10`|no|Specify the timeout in seconds Ansible should use in requests to the Ansible Automation Platform host.|| +|`controller_schedules`|`see below`|yes|Data structure describing your schedule or schedules Described below. Alias: schedules || + +### Enforcing defaults + +The following Variables compliment each other. +If Both variables are not set, enforcing default values is not done. +Enabling these variables enforce default values on options that are optional in the controller API. +This should be enabled to enforce configuration and prevent configuration drift. It is recomended to be enabled, however it is not enforced by default. + +Enabling this will enforce configurtion without specifying every option in the configuration files. + +'controller_configuration_schedules_enforce_defaults' defaults to the value of 'aap_configuration_enforce_defaults' if it is not explicitly called. This allows for enforced defaults to be toggled for the entire suite of controller configuration roles with a single variable, or for the user to selectively use it. + +|Variable Name|Default Value|Required|Description| +|`controller_configuration_schedules_enforce_defaults`|`False`|no|Whether or not to enforce default option values on only the applications role| +|`aap_configuration_enforce_defaults`|`False`|no|This variable enables enforced default values as well, but is shared across multiple roles, see above.| + +### Secure Logging Variables + +The following Variables compliment each other. +If Both variables are not set, secure logging defaults to false. +The role defaults to False as normally the add schedules task does not include sensitive information. +controller_configuration_schedules_secure_logging defaults to the value of aap_configuration_secure_logging if it is not explicitly called. This allows for secure logging to be toggled for the entire suite of controller configuration roles with a single variable, or for the user to selectively use it. + +|Variable Name|Default Value|Required|Description| +|`controller_configuration_schedules_secure_logging`|`False`|no|Whether or not to include the sensitive Schedules role tasks in the log. Set this value to `True` if you will be providing your sensitive values from elsewhere.| +|`aap_configuration_secure_logging`|`False`|no|This variable enables secure logging as well, but is shared across multiple roles, see above.| + +### Asynchronous Retry Variables + +The following Variables set asynchronous retries for the role. +If neither of the retries or delay or retries are set, they will default to their respective defaults. +This allows for all items to be created, then checked that the task finishes successfully. +This also speeds up the overall role. + +|Variable Name|Default Value|Required|Description| +|`aap_configuration_async_retries`|30|no|This variable sets the number of retries to attempt for the role globally.| +|`controller_configuration_schedules_async_retries`|`{{ aap_configuration_async_retries }}`|no|This variable sets the number of retries to attempt for the role.| +|`aap_configuration_async_delay`|1|no|This sets the delay between retries for the role globally.| +|`controller_configuration_schedules_async_delay`|`aap_configuration_async_delay`|no|This sets the delay between retries for the role.| +|`aap_configuration_loop_delay`|0|no|This sets the pause between each item in the loop for the roles globally. To help when API is getting overloaded.| +|`controller_configuration_schedules_loop_delay`|`aap_configuration_loop_delay`|no|This sets the pause between each item in the loop for the role. To help when API is getting overloaded.| +|`aap_configuration_async_dir`|`null`|no|Sets the directory to write the results file for async tasks. The default value is set to `null` which uses the Ansible Default of `/root/.ansible_async/`.| + +## Data Structure + +### Schedule Variables + +|Variable Name|Default Value|Required|Type|Description| +|`name`|""|yes|str|Name of Job Template| +|`new_name`|""|str|no|Setting this option will change the existing name (looked up via the name field).| +|`description`|`False`|no|str|Description to use for the job template.| +|`rrule`|""|yes|str|A value representing the schedules iCal recurrence rule. See the awx.awx.schedule plugin for help constructing this value| +|`extra_data`|`{}`|no|dict|Extra vars for the job template. Only allowed if prompt on launch| +|`inventory`|""|no|str|Inventory applied to job template, assuming the job template prompts for an inventory.| +|`credentials`|""|no|list|List of credentials applied as a prompt, assuming job template prompts for credentials| +|`scm_branch`|Project default|no|str|Branch to use in the job run. Project default used if not set. Only allowed if `allow_override` set to true on project| +|`execution_environment`|Job Template default|no|str|Execution Environment applied as a prompt. Job Template default used if not set. Only allowed if `ask_execution_environment_on_launch` set to true on Job Template| +|`forks`|Job Template default|no|str|Forks applied as a prompt. Job Template default used if not set. Only allowed if `ask_forks_on_launch` set to true on Job Template| +|`instance_groups`|Job Template default|no|str| List of Instance Groups applied as a prompt. Job Template default used if not set. Only allowed if `ask_instance_groups_on_launch` set to true on Job Template| +|`job_slice_count`|Job Template default|no|str|Job Slice Count to use in the job run. Job Template default used if not set. Only allowed if `ask_job_slice_count_on_launch` set to true on Job Template| +|`labels`|Job Template default|no|list|List of labels to use in the job run. Job Template default used if not set. Only allowed if `ask_labels_on_launch` set to true on Job Template| +|`timeout`|Job Template default|no|str|Timeout to use in the job run. Job Template default used if not set. Only allowed if `ask_timeout_on_launch` set to true on Job Template| +|`job_type`|Job template default|no|str|The job type used for the job template.| +|`job_tags`|""|no|str|Comma separated list of tags to apply to the job| +|`skip_tags`|""|no|str|Comma separated list of tags to skip for the job| +|`limit`|""|no|str|A host pattern to constrain the list of hosts managed or affected by the playbook| +|`diff_mode`|Job template default|no|bool|Enable diff mode for the job template| +|`verbosity`|Job template default|no|int|Level of verbosity for the job. Only allowed if configured to prompt on launch| +|`unified_job_template`|""|no|string|The name of object that is being targeted by the schedule. Example objects include projects, inventory sources, and templates. Required if state='present.| +|`organization`|""|no|str|The organization the unified job template exists in. Used for looking up the unified job template, not a direct model field.| +|`enabled`|`true`|no|bool|Enabled processing of this job template| +|`state`|`present`|no|str|Desired state of the resource.| + +### Standard Schedule Data Structure + +#### Json Example + +```json +"controller_schedules": [ + { + "name": "Demo Schedule", + "description": "A demonstration", + "unified_job_template": "Demo Job Template", + "rrule": "DTSTART:20191219T130551Z RRULE:FREQ=DAILY;INTERVAL=1;COUNT=1", + "extra_data": { + "scheduled": true + }, + "verbosity": 1 + } + ] + +``` + +#### Yaml Example + +```yaml +controller_schedules: + - name: Simple Example Schedule + description: A demonstration without any additional options + unified_job_template: Demo Job Template + rrule: "DTSTART:20191219T130551Z RRULE:FREQ=DAILY;INTERVAL=1;COUNT=1" + - name: Demo Schedule with extra options + description: A demonstration + unified_job_template: Demo Job Template + rrule: "DTSTART:20191219T130551Z RRULE:FREQ=DAILY;INTERVAL=1;COUNT=1" + # Note that this example requires the relevant ask_*_on_launch to be true + extra_data: + scheduled: true + verbosity: 1 +``` + +## Playbook Examples + +### Standard Role Usage + +```yaml +- name: Playbook to configure ansible controller post installation + hosts: localhost + connection: local + # Define following vars here, or in platform_configs/controller_auth.yml + # aap_hostname: ansible-controller-web-svc-test-project.example.com + # aap_username: admin + # aap_password: changeme + pre_tasks: + - name: Include vars from platform_configs directory + ansible.builtin.include_vars: + dir: ./yaml + ignore_files: [controller_config.yml.template] + extensions: ["yml"] + roles: + - {role: infra.aap_configuration.schedules, when: controller_schedules is defined} +``` + +## License + +[GPL-3.0](https://github.com/redhat-cop/aap_configuration#licensing) + +## Author + +[Tom Page](https://github.com/Tompage1994) diff --git a/collections/controller_configuration/controller_settings.md b/collections/controller_configuration/controller_settings.md new file mode 100644 index 0000000..375d5b3 --- /dev/null +++ b/collections/controller_configuration/controller_settings.md @@ -0,0 +1,154 @@ +--- +layout: default +title: controller_settings +parent: infra.controller_configuration +--- + +# controller_configuration.settings + +An Ansible role to alter Settings on Ansible Controller. + +## Requirements + +ansible-galaxy collection install -r tests/collections/requirements.yml to be installed +Currently: + awx.awx + or + ansible.controller + +## Variables + +|Variable Name|Default Value|Required|Description|Example| +|`platform_state`|"present"|no|The state all objects will take unless overridden by object default|'absent'| +|`aap_hostname`|""|yes|URL to the Ansible Automation Platform Server.|127.0.0.1| +|`aap_validate_certs`|`True`|no|Whether or not to validate the Ansible Automation Platform Server's SSL certificate.|| +|`aap_username`|""|no|Admin User on the Ansible Automation Platform Server. Either username / password or oauthtoken need to be specified.|| +|`aap_password`|""|no|Platform Admin User's password on the Server. This should be stored in an Ansible Vault at vars/platform-secrets.yml or elsewhere and called from a parent playbook.|| +|`aap_token`|""|no|Controller Admin User's token on the Ansible Automation Platform Server. This should be stored in an Ansible Vault at or elsewhere and called from a parent playbook. Either username / password or oauthtoken need to be specified.|| +|`aap_request_timeout`|`10`|no|Specify the timeout in seconds Ansible should use in requests to the Ansible Automation Platform host.|| +|`controller_settings`|`see below`|yes|Data structure describing your settings described below.|| + +### Secure Logging Variables + +The following Variables compliment each other. +If Both variables are not set, secure logging defaults to false. +The role defaults to False as normally the add settings task does not include sensitive information. +controller_configuration_settings_secure_logging defaults to the value of aap_configuration_secure_logging if it is not explicitly called. This allows for secure logging to be toggled for the entire suite of configuration roles with a single variable, or for the user to selectively use it. + +|Variable Name|Default Value|Required|Description| +|`controller_configuration_settings_secure_logging`|`False`|no|Whether or not to include the sensitive Settings role tasks in the log. Set this value to `True` if you will be providing your sensitive values from elsewhere.| +|`aap_configuration_secure_logging`|`False`|no|This variable enables secure logging as well, but is shared across multiple roles, see above.| + +### Asynchronous Retry Variables + +The following Variables set asynchronous retries for the role. +If neither of the retries or delay or retries are set, they will default to their respective defaults. +This allows for all items to be created, then checked that the task finishes successfully. +This also speeds up the overall role. + +|Variable Name|Default Value|Required|Description| +|`aap_configuration_async_retries`|30|no|This variable sets the number of retries to attempt for the role globally.| +|`controller_configuration_settings_async_retries`|`{{ aap_configuration_async_retries }}`|no|This variable sets the number of retries to attempt for the role.| +|`aap_configuration_async_delay`|1|no|This sets the delay between retries for the role globally.| +|`controller_configuration_settings_async_delay`|`aap_configuration_async_delay`|no|This sets the delay between retries for the role.| +|`aap_configuration_loop_delay`|0|no|This sets the pause between each item in the loop for the roles globally. To help when API is getting overloaded.| +|`controller_configuration_settings_loop_delay`|`aap_configuration_loop_delay`|no|This sets the pause between each item in the loop for the role. To help when API is getting overloaded.| +|`aap_configuration_async_dir`|`null`|no|Sets the directory to write the results file for async tasks. The default value is set to `null` which uses the Ansible Default of `/root/.ansible_async/`.| + +## Data Structure + +There are two choices for entering settings. Either provide as a single dict under `settings` or individually as `name` `value`. In the first case `controller_settings` will simply be an individual dict, but in the second case, it will be a list. + +### Setting Variables + +|Variable Name|Default Value|Required|Description| +|`settings`|{}|no|Dict of key-value pairs of settings| +|`name`|""|no|Name of the setting to set.| +|`value`|""|no|Value of the setting.| + +### Standard Setting Data Structure - as a dict + +#### Json Dict Example + +```json +{ + "controller_settings": { + "settings": { + "AUTH_LDAP_USER_DN_TEMPLATE": "uid=%(user)s,ou=Users,dc=example,dc=com", + "AUTH_LDAP_BIND_PASSWORD": "password" + } + } +} + +``` + +#### Yaml Dict Example + +```yaml +controller_settings: + settings: + AUTH_LDAP_USER_DN_TEMPLATE: "uid=%(user)s,ou=Users,dc=example,dc=com" + AUTH_LDAP_BIND_PASSWORD: "password" + +``` + +### Standard Setting Data Structure - as a list + +#### Json List Example + +```json +{ + "controller_settings": [ + { + "name": "AUTH_LDAP_USER_DN_TEMPLATE", + "value": "uid=%(user)s,ou=Users,dc=example,dc=com" + }, + { + "name": "AUTH_LDAP_BIND_PASSWORD", + "value": "password" + } + ] +} + +``` + +#### Yaml List Example + +```yaml +controller_settings: + - name: AUTH_LDAP_USER_DN_TEMPLATE + value: "uid=%(user)s,ou=Users,dc=example,dc=com" + - name: AUTH_LDAP_BIND_PASSWORD + value: "password" +``` + +## Playbook Examples + +### Standard Role Usage + +```yaml +- name: Playbook to configure ansible controller post installation + hosts: localhost + connection: local + # Define following vars here, or in platform_configs/controller_auth.yml + # aap_hostname: ansible-controller-web-svc-test-project.example.com + # aap_username: admin + # aap_password: changeme + pre_tasks: + - name: Include vars from platform_configs directory + ansible.builtin.include_vars: + dir: ./yaml + ignore_files: [controller_config.yml.template] + extensions: ["yml"] + roles: + - {role: infra.aap_configuration.settings, when: controller_settings is defined} +``` + +## License + +[GPL-3.0](https://github.com/redhat-cop/aap_configuration#licensing) + +## Author + +[Kedar Kulkarni](https://github.com/kedark3) +[Sean Sullivan](https://github.com/sean-m-sullivan) diff --git a/collections/controller_configuration/controller_teams.md b/collections/controller_configuration/controller_teams.md new file mode 100644 index 0000000..4261e8e --- /dev/null +++ b/collections/controller_configuration/controller_teams.md @@ -0,0 +1,113 @@ +--- +layout: default +title: controller_teams +parent: infra.controller_configuration +--- + +# controller_configuration.teams + +## Description + +An Ansible Role to create/update/remove Teams on Ansible Controller. + +## Requirements + +ansible-galaxy collection install -r tests/collections/requirements.yml to be installed +Currently: + awx.awx + or + ansible.controller + +## Variables + +|Variable Name|Default Value|Required|Description|Example| +|`platform_state`|"present"|no|The state all objects will take unless overridden by object default|'absent'| +|`aap_hostname`|""|yes|URL to the Ansible Automation Platform Server.|127.0.0.1| +|`aap_validate_certs`|`True`|no|Whether or not to validate the Ansible Automation Platform Server's SSL certificate.|| +|`aap_username`|""|no|Admin User on the Ansible Automation Platform Server. Either username / password or oauthtoken need to be specified.|| +|`aap_password`|""|no|Platform Admin User's password on the Server. This should be stored in an Ansible Vault at vars/platform-secrets.yml or elsewhere and called from a parent playbook.|| +|`aap_token`|""|no|Controller Admin User's token on the Ansible Automation Platform Server. This should be stored in an Ansible Vault at or elsewhere and called from a parent playbook. Either username / password or oauthtoken need to be specified.|| +|`aap_request_timeout`|`10`|no|Specify the timeout in seconds Ansible should use in requests to the Ansible Automation Platform host.|| +|`aap_teams`|`see below`|yes|Data structure describing your Teams described below. Alias: teams || + +### Enforcing defaults + +The following Variables compliment each other. +If Both variables are not set, enforcing default values is not done. +Enabling these variables enforce default values on options that are optional in the controller API. +This should be enabled to enforce configuration and prevent configuration drift. It is recomended to be enabled, however it is not enforced by default. + +Enabling this will enforce configurtion without specifying every option in the configuration files. + +'controller_configuration_platform_teams_enforce_defaults' defaults to the value of 'aap_configuration_enforce_defaults' if it is not explicitly called. This allows for enforced defaults to be toggled for the entire suite of controller configuration roles with a single variable, or for the user to selectively use it. + +|Variable Name|Default Value|Required|Description| +|`controller_configuration_platform_teams_enforce_defaults`|`False`|no|Whether or not to enforce default option values on only the applications role| +|`aap_configuration_enforce_defaults`|`False`|no|This variable enables enforced default values as well, but is shared across multiple roles, see above.| + +### Secure Logging Variables + +The following Variables compliment each other. +If Both variables are not set, secure logging defaults to false. +The role defaults to False as normally the add teams task does not include sensitive information. +`controller_configuration_platform_teams_secure_logging` defaults to the value of `aap_configuration_secure_logging` if it is not explicitly called. This allows for secure logging to be toggled for the entire suite of configuration roles with a single variable, or for the user to selectively use it. + +|Variable Name|Default Value|Required|Description| +|`controller_configuration_platform_teams_secure_logging`|`False`|no|Whether or not to include the sensitive teams role tasks in the log. Set this value to `True` if you will be providing your sensitive values from elsewhere.| +|`aap_configuration_secure_logging`|`False`|no|This variable enables secure logging as well, but is shared across multiple roles, see above.| + +### Asynchronous Retry Variables + +The following Variables set asynchronous retries for the role. +If neither of the retries or delay or retries are set, they will default to their respective defaults. +This allows for all items to be created, then checked that the task finishes successfully. +This also speeds up the overall role. + +|Variable Name|Default Value|Required|Description| +|`aap_configuration_async_retries`|30|no|This variable sets the number of retries to attempt for the role globally.| +|`controller_configuration_platform_teams_async_retries`|`{{ aap_configuration_async_retries }}`|no|This variable sets the number of retries to attempt for the role.| +|`aap_configuration_async_delay`|1|no|This sets the delay between retries for the role globally.| +|`controller_configuration_platform_teams_async_delay`|`aap_configuration_async_delay`|no|This sets the delay between retries for the role.| +|`aap_configuration_loop_delay`|0|no|This sets the pause between each item in the loop for the roles globally. To help when API is getting overloaded.| +|`controller_configuration_teams_loop_delay`|`aap_configuration_loop_delay`|no|This sets the pause between each item in the loop for the role. To help when API is getting overloaded.| +|`aap_configuration_async_dir`|`null`|no|Sets the directory to write the results file for async tasks. The default value is set to `null` which uses the Ansible Default of `/root/.ansible_async/`.| + +### Data structure `aap_teams:` should include following vars + +|Variable Name|Default Value|Required|Type|Description| +|`name`||yes|str|The desired team name to create or modify| +|`new_name`||no|str|To use when changing a team's name.| +|`description`|omitted|no|str|The team description| +|`organization`||yes|str|The organization in which team will be created| +|`state`|`present`|no|str|Desired state of the resource.| + +## Playbook Examples + +### Standard Role Usage + +``` yaml +- name: Playbook to configure ansible controller post installation + hosts: localhost + connection: local + # Define following vars here, or in platform_configs/controller_auth.yml + # aap_hostname: ansible-controller-web-svc-test-project.example.com + # aap_username: admin + # aap_password: changeme + pre_tasks: + - name: Include vars from platform_configs directory + ansible.builtin.include_vars: + dir: ./yaml + ignore_files: [controller_config.yml.template] + extensions: ["yml"] + roles: + - {role: infra.aap_configuration.teams, when: aap_teams is defined} +``` + +## License + +[GPL-3.0](https://github.com/redhat-cop/aap_configuration#licensing) + +## Author + +[Andrew J. Huffman](https://github.com/ahuffman) +[Kedar Kulkarni](https://github.com/kedark3) diff --git a/collections/controller_configuration/controller_users.md b/collections/controller_configuration/controller_users.md new file mode 100644 index 0000000..41507cb --- /dev/null +++ b/collections/controller_configuration/controller_users.md @@ -0,0 +1,147 @@ +--- +layout: default +title: controller_users +parent: infra.controller_configuration +--- + +# controller_configuration.users + +## Description + +An Ansible Role to add/update/remove users to on Ansible Controller. + +## Requirements + +ansible-galaxy collection install -r tests/collections/requirements.yml to be installed +Currently: + awx.awx + or + ansible.controller + +## Variables + +|Variable Name|Default Value|Required|Description|Example| +|`platform_state`|"present"|no|The state all objects will take unless overridden by object default|'absent'| +|`aap_hostname`|""|yes|URL to the Ansible Automation Platform Server.|127.0.0.1| +|`aap_validate_certs`|`True`|no|Whether or not to validate the Ansible Automation Platform Server's SSL certificate.|| +|`aap_username`|""|no|Admin User on the Ansible Automation Platform Server. Either username / password or oauthtoken need to be specified.|| +|`aap_password`|""|no|Platform Admin User's password on the Server. This should be stored in an Ansible Vault at vars/platform-secrets.yml or elsewhere and called from a parent playbook.|| +|`aap_token`|""|no|Controller Admin User's token on the Ansible Automation Platform Server. This should be stored in an Ansible Vault at or elsewhere and called from a parent playbook. Either username / password or oauthtoken need to be specified.|| +|`aap_request_timeout`|`10`|no|Specify the timeout in seconds Ansible should use in requests to the Ansible Automation Platform host.|| +|`aap_user_accounts`|`see below`|yes|Data structure describing your user entries described below. Alias: users || +|`controller_user_default_password`|""|no|Global variable to set the password for all users.|| + +### Enforcing defaults + +The following Variables compliment each other. +If Both variables are not set, enforcing default values is not done. +Enabling these variables enforce default values on options that are optional in the controller API. +This should be enabled to enforce configuration and prevent configuration drift. It is recomended to be enabled, however it is not enforced by default. + +Enabling this will enforce configurtion without specifying every option in the configuration files. + +'controller_configuration_users_enforce_defaults' defaults to the value of 'aap_configuration_enforce_defaults' if it is not explicitly called. This allows for enforced defaults to be toggled for the entire suite of controller configuration roles with a single variable, or for the user to selectively use it. + +|Variable Name|Default Value|Required|Description| +|`controller_configuration_users_enforce_defaults`|`False`|no|Whether or not to enforce default option values on only the applications role| +|`aap_configuration_enforce_defaults`|`False`|no|This variable enables enforced default values as well, but is shared across multiple roles, see above.| + +### Secure Logging Variables + +The following Variables compliment each other. +If Both variables are not set, secure logging defaults to false. +The role defaults to False as normally the add user task does not include sensitive information. +`controller_configuration_user_secure_logging` defaults to the value of `aap_configuration_secure_logging` if it is not explicitly called. This allows for secure logging to be toggled for the entire suite of configuration roles with a single variable, or for the user to selectively use it. + +|Variable Name|Default Value|Required|Description| +|`controller_configuration_user_secure_logging`|`False`|no|Whether or not to include the sensitive user role tasks in the log. Set this value to `True` if you will be providing your sensitive values from elsewhere.| +|`aap_configuration_secure_logging`|`False`|no|This variable enables secure logging as well, but is shared across multiple roles, see above.| + +### Asynchronous Retry Variables + +The following Variables set asynchronous retries for the role. +If neither of the retries or delay or retries are set, they will default to their respective defaults. +This allows for all items to be created, then checked that the task finishes successfully. +This also speeds up the overall role. + +|Variable Name|Default Value|Required|Description| +|`aap_configuration_async_retries`|30|no|This variable sets the number of retries to attempt for the role globally.| +|`controller_configuration_users_async_retries`|`{{ aap_configuration_async_retries }}`|no|This variable sets the number of retries to attempt for the role.| +|`aap_configuration_async_delay`|1|no|This sets the delay between retries for the role globally.| +|`controller_configuration_users_async_delay`|`aap_configuration_async_delay`|no|This sets the delay between retries for the role.| +|`aap_configuration_loop_delay`|0|no|This sets the pause between each item in the loop for the roles globally. To help when API is getting overloaded.| +|`controller_configuration_users_loop_delay`|`aap_configuration_loop_delay`|no|This sets the pause between each item in the loop for the role. To help when API is getting overloaded.| +|`aap_configuration_async_dir`|`null`|no|Sets the directory to write the results file for async tasks. The default value is set to `null` which uses the Ansible Default of `/root/.ansible_async/`.| + +## Data Structure + +### User Account Variables + +|Variable Name|Default Value|Required|Type|Description| +|`username`|""|yes|str|The username of the user| +|`new_username`|""|yes|str|Setting this option will change the existing username (looked up via the username field).| +|`password`|"{{ controller_user_default_password }}"|no|str|The password of the user| +|`email`|""|yes|str|The email of the user| +|`first_name`|""|no|str|The first name of the user| +|`last_name`|""|no|str|The last name of the user| +|`is_superuser`|false|no|bool|Whether the user is a superuser| +|`is_system_auditor`|false|no|bool|Whether the user is an auditor| +|`organization`|""|no|str|The name of the organization the user belongs to.
Added in awx.awx >= 20.0.0 DOES NOT exist in ansible.controller yet.| +|`state`|`present`|no|str|Desired state of the resource.| +|`update_secrets`|true|no|bool| True will always change password if user specifies password, even if API gives $encrypted$ for password. False will only set the password if other values change too.| + +### Standard User Data Structure + +#### Json Example + +```json +{ + "aap_user_accounts": [ + { + "user": "jsmith", + "is_superuser": false, + "password": "p4ssword", + "email": "jsmith@example.com" + } + ] +} +``` + +#### Yaml Example + +```yaml +aap_user_accounts: + - user: controller_user + is_superuser: false + password: aap_password +``` + +## Playbook Examples + +### Standard Role Usage + +```yaml +- name: Playbook to configure ansible controller post installation + hosts: localhost + connection: local + # Define following vars here, or in platform_configs/controller_auth.yml + # aap_hostname: ansible-controller-web-svc-test-project.example.com + # aap_username: admin + # aap_password: changeme + pre_tasks: + - name: Include vars from platform_configs directory + ansible.builtin.include_vars: + dir: ./yaml + ignore_files: [controller_config.yml.template] + extensions: ["yml"] + roles: + - {role: infra.aap_configuration.users, when: aap_user_accounts is defined} +``` + +## License + +[GPL-3.0](https://github.com/redhat-cop/aap_configuration#licensing) + +## Author + +[Tom Page](https://github.com/Tompage1994) diff --git a/collections/controller_configuration/controller_workflow_job_templates.md b/collections/controller_configuration/controller_workflow_job_templates.md new file mode 100644 index 0000000..80a9d70 --- /dev/null +++ b/collections/controller_configuration/controller_workflow_job_templates.md @@ -0,0 +1,429 @@ +--- +layout: default +title: controller_workflow_job_templates +parent: infra.controller_configuration +--- + +# controller_configuration.workflow_job_templates + +## Description + +An Ansible Role to create/update/remove Workflow Job Templates on Ansible Controller. + +## Requirements + +ansible-galaxy collection install -r tests/collections/requirements.yml to be installed +Currently: + awx.awx + or + ansible.controller + +## Variables + +|Variable Name|Default Value|Required|Description|Example| +|`platform_state`|"present"|no|The state all objects will take unless overridden by object default|'absent'| +|`aap_hostname`|""|yes|URL to the Ansible Automation Platform Server.|127.0.0.1| +|`aap_validate_certs`|`True`|no|Whether or not to validate the Ansible Automation Platform Server's SSL certificate.|| +|`aap_username`|""|no|Admin User on the Ansible Automation Platform Server. Either username / password or oauthtoken need to be specified.|| +|`aap_password`|""|no|Platform Admin User's password on the Server. This should be stored in an Ansible Vault at vars/platform-secrets.yml or elsewhere and called from a parent playbook.|| +|`aap_token`|""|no|Controller Admin User's token on the Ansible Automation Platform Server. This should be stored in an Ansible Vault at or elsewhere and called from a parent playbook. Either username / password or oauthtoken need to be specified.|| +|`aap_request_timeout`|`10`|no|Specify the timeout in seconds Ansible should use in requests to the Ansible Automation Platform host.|| +|`controller_workflows`|`see below`|yes|Data structure describing your workflow job templates described below. Alias: workflow_job_templates || + +### Enforcing defaults + +The following Variables compliment each other. +If Both variables are not set, enforcing default values is not done. +Enabling these variables enforce default values on options that are optional in the controller API. +This should be enabled to enforce configuration and prevent configuration drift. It is recomended to be enabled, however it is not enforced by default. + +Enabling this will enforce configurtion without specifying every option in the configuration files. + +'controller_configuration_workflows_enforce_defaults' defaults to the value of 'aap_configuration_enforce_defaults' if it is not explicitly called. This allows for enforced defaults to be toggled for the entire suite of controller configuration roles with a single variable, or for the user to selectively use it. + +|Variable Name|Default Value|Required|Description| +|`controller_configuration_workflows_enforce_defaults`|`False`|no|Whether or not to enforce default option values on only the applications role| +|`aap_configuration_enforce_defaults`|`False`|no|This variable enables enforced default values as well, but is shared across multiple roles, see above.| + +### Secure Logging Variables + +The following Variables compliment each other. +If Both variables are not set, secure logging defaults to false. +The role defaults to False as normally the add Workflow Job Templates task does not include sensitive information. +workflow_job_templates_secure_logging defaults to the value of aap_configuration_secure_logging if it is not explicitly called. This allows for secure logging to be toggled for the entire suite of genie roles with a single variable, or for the user to selectively use it. + +|Variable Name|Default Value|Required|Description| +|`workflow_job_templates_secure_logging`|`False`|no|Whether or not to include the sensitive Workflow Job Templates role tasks in the log. Set this value to `True` if you will be providing your sensitive values from elsewhere.| +|`aap_configuration_secure_logging`|`False`|no|This variable enables secure logging as well, but is shared across multiple roles, see above.| + +### Asynchronous Retry Variables + +The following Variables set asynchronous retries for the role. +If neither of the retries or delay or retries are set, they will default to their respective defaults. +This allows for all items to be created, then checked that the task finishes successfully. +This also speeds up the overall role. + +|Variable Name|Default Value|Required|Description| +|`aap_configuration_async_retries`|30|no|This variable sets the number of retries to attempt for the role globally.| +|`controller_configuration_workflow_async_retries`|`{{ aap_configuration_async_retries }}`|no|This variable sets the number of retries to attempt for the role.| +|`aap_configuration_async_delay`|1|no|This sets the delay between retries for the role globally.| +|`controller_configuration_workflow_async_delay`|`aap_configuration_async_delay`|no|This sets the delay between retries for the role.| +|`aap_configuration_loop_delay`|0|no|This sets the pause between each item in the loop for the roles globally. To help when API is getting overloaded.| +|`controller_configuration_workflow_loop_delay`|`aap_configuration_loop_delay`|no|This sets the pause between each item in the loop for the role. To help when API is getting overloaded.| +|`aap_configuration_async_dir`|`null`|no|Sets the directory to write the results file for async tasks. The default value is set to `null` which uses the Ansible Default of `/root/.ansible_async/`.| + +## Data Structure + +### Variables For Workflow Job Template + +|Variable Name|Default Value|Required|Type|Description| +|`name`|""|yes|str|Name of Workflow Job Template| +|`new_name`|""|str|no|Setting this option will change the existing name (looked up via the name field).| +|`copy_from`|""|no|str|Name or id to copy the Workflow template from. This will copy an existing workflow and change any parameters supplied.| +|`description`|""|no|str|Description to use for the job template.| +|`organization`|""|no|list|Organization the workflow job template exists in. Used to lookup the object, cannot be changed with this module| +|`ask_inventory_on_launch`|""|no|bool|Prompt user for inventory on launch.| +|`ask_limit_on_launch`|""|no|bool|Prompt user for a limit on launch.| +|`ask_scm_branch_on_launch`|""|no|bool|Prompt user for scm branch on launch.| +|`ask_variables_on_launch`|""|no|bool|Prompt user for extra_vars on launch.| +|`extra_vars`|""|no|dict|Specify extra_vars for the template.| +|`allow_simultaneous`|""|no|bool|Allow simultaneous runs of the workflow job template.| +|`inventory`|""|no|str|Inventory applied as a prompt, assuming job template prompts for inventory| +|`limit`|""|no|str|Limit applied as a prompt, assuming job template prompts for limit| +|`labels`|""|no|str|The labels applied to this job template. NOTE: Labels must be created with the [labels](https://github.com/redhat-cop/aap_configuration/tree/devel/roles/controller_labels) role first, an error will occur if the label supplied to this role does not exist.| +|`ask_labels_on_launch`|""|no|bool|Prompt user for labels on launch.| +|`job_tags`|""|no|str|Comma separated list of the tags to use for the workflow job template.| +|`skip_tags`|""|no|str|Comma separated list of the tags to skip for the workflow job template.| +|`ask_tags_on_launch`|""|no|bool|Prompt user for job tags on launch.| +|`ask_skip_tags_on_launch`|""|no|bool|Prompt user for job tags to skip on launch.| +|`notification_templates_approvals`|""|no|list|The notifications on approval to use for this organization in a list.| +|`notification_templates_error`|""|no|list|The notifications on error to use for this organization in a list.| +|`notification_templates_started`|""|no|list|The notifications on started to use for this organization in a list.| +|`notification_templates_success`|""|no|list|The notifications on success to use for this organization in a list.| +|`scm_branch`|""|no|str|SCM branch applied as a prompt, assuming job template prompts for SCM branch| +|`state`|`present`|no|str|Desired state of the resource.| +|`workflow_nodes`|""|no|dict|A json list of nodes and their corresponding options. The sub-options are in the module doc.| +|`destroy_current_nodes`|""|no|dict|Set in order to destroy current schema on the workflow, used in cases where drastic changes to schema are happening.| +|`survey_enabled`|""|no|bool|Enable a survey on the job template.| +|`survey_spec`|""|no|dict|JSON/YAML dict formatted survey definition.| +|`survey`|""|no|dict|JSON/YAML dict formatted survey definition. Alias of survey_spec| +|`webhook_service`|""|no|str|Service that webhook requests will be accepted from (github, gitlab)| +|`webhook_credential`|""|no|str|Personal Access Token for posting back the status to the service API| + +### Variables For Workflow Job Template Node + +|Variable Name|Default Value|Required|Type|Description| +|`workflow_job_template`|""|yes|str|The workflow job template the node exists in. Used for looking up the node, cannot be modified after creation.| +|`identifier`|""|yes|str|An identifier for this node that is unique within its workflow. It is copied to workflow job nodes corresponding to this node. This functions the same as the name field for other resources, however if it is not set, it will be set to a random UUID4 value. Recommended to use Column and row numbers for identifiers such as Node401. [Refer to this documentation for more](https://github.com/ansible/awx/blob/devel/docs/workflow.md)| +|`unified_job_template`|""|no|str|Name of unified job template to run in the workflow. Can be a job template, project, inventory source, etc. This parameter is mutually exclusive with approval_node.| +|`lookup_organization`|""|no|str|Organization the inventories, job templates, projects, or workflows the items exists in. Used to help lookup the object, for organization roles see organization. If not provided, will lookup by name only, which does not work with duplicates.| +|`execution_environment`|Job Template default|no|str|Execution Environment applied as a prompt. Job Template default used if not set. Only allowed if `ask_execution_environment_on_launch` set to true on Job Template| +|`forks`|Job Template default|no|str|Forks applied as a prompt. Job Template default used if not set. Only allowed if `ask_forks_on_launch` set to true on Job Template| +|`instance_groups`|Job Template default|no|str| List of Instance Groups applied as a prompt. Job Template default used if not set. Only allowed if `ask_instance_groups_on_launch` set to true on Job Template| +|`job_slice_count`|Job Template default|no|str|Job Slice Count to use in the job run. Job Template default used if not set. Only allowed if `ask_job_slice_count_on_launch` set to true on Job Template| +|`labels`|Job Template default|no|list|List of labels to use in the job run. Job Template default used if not set. Only allowed if `ask_labels_on_launch` set to true on Job Template. NOTE: Labels must be created with the [labels](https://github.com/redhat-cop/aap_configuration/tree/devel/roles/controller_labels) role first, an error will occur if the label supplied to this role does not exist.| +|`timeout`|Job Template default|no|str|Timeout to use in the job run. Job Template default used if not set. Only allowed if `ask_timeout_on_launch` set to true on Job Template| +|`approval_node`|""|no|str|A dictionary of Name, description, and timeout values for the approval node. This parameter is mutually exclusive with unified_job_template.| +|`organization`|""|no|str|The organization of the workflow job template the node exists in. Used for looking up the workflow, not a direct model field.| +|`all_parents_must_converge`|""|no|bool|If enabled then the node will only run if all of the parent nodes have met the criteria to reach this node| +|`always_nodes`|""|no|list|Nodes that will run after this node completes.| +|`failure_nodes`|""|no|list|Nodes that will run after this node completes.| +|`success_nodes`|""|no|list|Nodes that will run after this node completes.| +|`verbosity`|""|no|str|Verbosity applied as a prompt, if job template prompts for verbosity| +|`state`|""|no|str|Desired state of the resource| +|`credentials`|""|no|list|Credentials to be applied to job as launch-time prompts.| +|`diff_mode`|""|no|bool|Run diff mode, applied as a prompt, if job template prompts for diff mode| +|`extra_data`|""|no|dict|Variables to apply at launch time. Will only be accepted if job template prompts for vars or has a survey asking for those vars. extra_data are extra_vars at the node level and named so to match the module and the API. These are only for "ask extra vars on prompt" on a given job template.| +|`inventory`|""|no|str|Inventory applied as a prompt, if job template prompts for inventory| +|`job_tags`|""|no|str|NJob tags applied as a prompt, if job template prompts for job tags| +|`job_type`|""|no|str|Job type applied as a prompt, if job template prompts for job type| +|`limit`|""|no|str|Limit to act on, applied as a prompt, if job template prompts for limit| +|`scm_branch`|""|no|str|SCM branch applied as a prompt, if job template prompts for SCM branch| +|`skip_tags`|""|no|str|Tags to skip, applied as a prompt, if job template prompts for job tags| + +### Approval node dictionary + +|Variable Name|Default Value|Required|Type|Description| +|`name`|""|yes|str|Name of this workflow approval template.| +|`description`|""|no|str|Optional description of this workflow approval template.| +|`timeout`|0|no|int|The amount of time (in seconds) before the approval node expires and fails.| + +### Surveys + +Refer to the [Controller Api Guide](https://docs.ansible.com/ansible-tower/latest/html/towerapi/api_ref.html#/Job_Templates/Job_Templates_job_templates_survey_spec_create) for more information about forming surveys + +|Variable Name|Variable Description| +|`name`|Name of the survey| +|`description`|Description of the survey| +|`spec`|List of survey items, each a dictionary containing the following fields| +|`question_name`|Name of the field/item| +|`question_description`|Longer description| +|`required`|Boolean expressing if an answer is required| +|`type`|One of `text`, `password`, `integer`, `float`, `multiplechoice`or `multiselect`| +|`variable`|Name of Ansible Variable where to put the answer| +|`default`|Default value for the variable| +|`min`|Minimum value for a number type| +|`max`|Maximum value for a number type| +|`choices`|List of choices for a "multi" type| +|`new_question`|Boolean| + +### Workflow Data Structures + +This role accepts two data models. + +#### Simplified Workflow nodes + +A simple straightforward easy to maintain model using the var simplified_workflow_nodes. +However this is, not compatible with the schema option on the controller_workflow_job_template module and will result in errors. +Uses the variable 'simplified_workflow_nodes' to describe nodes as shown below. + +#### Simplified Workflow Node Data structure model + +##### Yaml Example + +```yaml +controller_workflows: + - name: Simple workflow schema + description: a basic workflow + extra_vars: '' + survey_enabled: false + allow_simultaneous: false + ask_variables_on_launch: false + inventory: + limit: + scm_branch: + ask_inventory_on_launch: false + ask_scm_branch_on_launch: false + ask_limit_on_launch: false + webhook_service: '' + webhook_credential: + organization: Default + schedules: [] + simplified_workflow_nodes: + - all_parents_must_converge: false + identifier: node101 + unified_job_template: RHVM-01 + credentials: [] + success_nodes: + - node201 + failure_nodes: [] + always_nodes: [] + - identifier: node201 + approval_node: + name: Simple approval node name + description: Approve this to proceed in workflow + timeout: 900 # 15 minutes + - all_parents_must_converge: false + identifier: node301 + unified_job_template: test-template-1 + credentials: [] + success_nodes: [] + failure_nodes: [] + always_nodes: [] + notification_templates_started: [] + notification_templates_success: [] + notification_templates_error: [] + notification_templates_approvals: [] + survey_spec: {} + +``` + +#### Controller Export Model + +This model is based off of the output from awx.awx.export, that is based on the API. +This is more complicated, However it allows the user to use the schema input on the role which runs much faster compared to the simplified model. +This can be under the subvariable 'workflow_nodes' or under the subvariable 'related.workflow_nodes' which is the output of controller_export. + +#### Controller Export Data structure model + +##### Yaml Export Example + +```yaml +controller_workflows: + - name: Simple workflow schema + description: a basic workflow + extra_vars: '' + survey_enabled: false + allow_simultaneous: false + ask_variables_on_launch: false + inventory: + limit: + scm_branch: + ask_inventory_on_launch: false + ask_scm_branch_on_launch: false + ask_limit_on_launch: false + webhook_service: '' + webhook_credential: + organization: + name: Default + workflow_nodes: + - all_parents_must_converge: false + identifier: node101 + unified_job_template: + name: RHVM-01 + type: job_template + organization: + name: Default + related: + success_nodes: + - workflow_job_template: + name: Simple workflow schema + identifier: node201 + - all_parents_must_converge: false + identifier: node201 + unified_job_template: + name: test-template-1 + type: job_template + organization: + name: Default + notification_templates_started: [] + notification_templates_success: [] + notification_templates_error: [] + notification_templates_approvals: [] + survey_spec: + name: '' + description: '' + spec: + - question_name: Basic Name + question_description: Name + required: true + type: text + variable: basic_name + min: 0 + max: 1024 + default: '' + choices: '' + new_question: true + +``` + +#### Json Export Example + +```json +{ + "controller_workflows": [ + { + "name": "Simple workflow schema", + "description": "a basic workflow", + "extra_vars": "", + "survey_enabled": false, + "allow_simultaneous": false, + "ask_variables_on_launch": false, + "inventory": null, + "limit": null, + "scm_branch": null, + "ask_inventory_on_launch": false, + "ask_scm_branch_on_launch": false, + "ask_limit_on_launch": false, + "webhook_service": "", + "webhook_credential": null, + "organization": { + "name": "Default" + }, + "related": { + "schedules": [ + + ], + "workflow_nodes": [ + { + "all_parents_must_converge": false, + "identifier": "node101", + "unified_job_template": { + "name": "RHVM-01", + "type": "job_template", + "organization": { "name": "Default" } + }, + "related": { + "credentials": [ + + ], + "success_nodes": [ + { + "workflow_job_template": { + "name": "Simple workflow schema" + }, + "identifier": "node201" + } + ], + "failure_nodes": [ + + ], + "always_nodes": [ + + ] + } + }, + { + "all_parents_must_converge": false, + "identifier": "node201", + "unified_job_template": { + "name": "test-template-1", + "type": "job_template", + "organization": { "name": "Default" } + }, + "related": { + "credentials": [ + + ], + "success_nodes": [ + + ], + "failure_nodes": [ + + ], + "always_nodes": [ + + ] + } + } + ], + "notification_templates_started": [ + + ], + "notification_templates_success": [ + + ], + "notification_templates_error": [ + + ], + "notification_templates_approvals": [ + + ], + "survey_spec": { + } + } + } + ] +} +``` + +## Playbook Examples + +### Standard Role Usage + +```yaml +- name: Playbook to configure ansible controller post installation + hosts: localhost + connection: local + # Define following vars here, or in platform_configs/controller_auth.yml + # aap_hostname: ansible-controller-web-svc-test-project.example.com + # aap_username: admin + # aap_password: changeme + pre_tasks: + - name: Include vars from platform_configs directory + ansible.builtin.include_vars: + dir: ./yaml + ignore_files: [controller_config.yml.template] + extensions: ["yml"] + roles: + - {role: infra.aap_configuration.workflow_job_templates, when: controller_workflows is defined} + +``` + +## License + +[GPL-3.0](https://github.com/redhat-cop/aap_configuration#licensing) + +## Author + +[Sean Sullivan](https://github.com/sean-m-sullivan) diff --git a/collections/controller_configuration/controller_workflow_launch.md b/collections/controller_configuration/controller_workflow_launch.md new file mode 100644 index 0000000..b8cd7ed --- /dev/null +++ b/collections/controller_configuration/controller_workflow_launch.md @@ -0,0 +1,98 @@ +--- +layout: default +title: controller_workflow_launch +parent: infra.controller_configuration +--- + +# controller_configuration.workflow_launch + +## Description + +An Ansible Role to launch a job template on Ansible Controller. + +## Requirements + +ansible-galaxy collection install -r tests/collections/requirements.yml to be installed +Currently: + awx.awx + or + ansible.controller + +## Variables + +|Variable Name|Default Value|Required|Description|Example| +|`platform_state`|"present"|no|The state all objects will take unless overridden by object default|'absent'| +|`aap_hostname`|""|yes|URL to the Ansible Automation Platform Server.|127.0.0.1| +|`aap_validate_certs`|`True`|no|Whether or not to validate the Ansible Automation Platform Server's SSL certificate.|| +|`aap_username`|""|no|Admin User on the Ansible Automation Platform Server. Either username / password or oauthtoken need to be specified.|| +|`aap_password`|""|no|Platform Admin User's password on the Server. This should be stored in an Ansible Vault at vars/platform-secrets.yml or elsewhere and called from a parent playbook.|| +|`aap_token`|""|no|Controller Admin User's token on the Ansible Automation Platform Server. This should be stored in an Ansible Vault at or elsewhere and called from a parent playbook. Either username / password or oauthtoken need to be specified.|| +|`aap_request_timeout`|`10`|no|Specify the timeout in seconds Ansible should use in requests to the Ansible Automation Platform host.|| +|`controller_workflow_launch_jobs`|`see below`|yes|Data structure describing workflow or workflows to launch Described below.|| + +### Secure Logging Variables + +The following Variables compliment each other. +If Both variables are not set, secure logging defaults to false. +The role defaults to False as normally the workflow launch task does not include sensitive information. +controller_configuration_workflow_launch_secure_logging defaults to the value of aap_configuration_secure_logging if it is not explicitly called. This allows for secure logging to be toggled for the entire suite of controller configuration roles with a single variable, or for the user to selectively use it. + +|Variable Name|Default Value|Required|Description| +|`controller_configuration_workflow_launch_secure_logging`|`False`|no|Whether or not to include the sensitive ad_hoc_command role tasks in the log. Set this value to `True` if you will be providing your sensitive values from elsewhere.| +|`aap_configuration_secure_logging`|`False`|no|This variable enables secure logging as well, but is shared across multiple roles, see above.| + +## Data Structure + +### Workflow Job Launch Variables + +|Variable Name|Default Value|Required|Type|Description| +|`name`|""|yes|str|The name or id of the project to update.| +|`organization`|""|no|str|Organization the workflow job template exists in. Used for lookup| +|`inventory`|""|no|str|Inventory to use for the job ran with this workflow, only used if prompt for inventory is set.| +|`limit`|""|no|str|Limit to use for the job_template.| +|`scm_branch`|""|no|str|A specific of the SCM project to run the template on.| +|`extra_vars`|""|no|str|Any extra vars required to launch the job. ask_extra_vars needs to be set to True via controller_job_template module.| +|`wait`|""|no|bool|Wait for the job to complete.| +|`interval`|2|no|int|The interval to request an update from controller.| +|`timeout`|""|no|int|If waiting for the job to complete this will abort after this amount of seconds.| + +### Standard Workflow Job Launch Data Structure + +#### Yaml Example + +```yaml +controller_workflow_launch_jobs: + - name: test-workflow + +``` + +## Playbook Examples + +### Standard Role Usage + +```yaml +- name: Playbook to configure ansible controller post installation + hosts: localhost + connection: local + # Define following vars here, or in platform_configs/controller_auth.yml + # aap_hostname: ansible-controller-web-svc-test-project.example.com + # aap_username: admin + # aap_password: changeme + pre_tasks: + - name: Include vars from platform_configs directory + ansible.builtin.include_vars: + dir: ./yaml + ignore_files: [controller_config.yml.template] + extensions: ["yml"] + roles: + - {role: infra.aap_configuration.workflow_launch, when: controller_workflow_launch_jobs is defined} + +``` + +## License + +[GPL-3.0](https://github.com/redhat-cop/aap_configuration#licensing) + +## Author + +[Sean Sullivan](https://github.com/sean-m-sullivan) diff --git a/collections/controller_configuration/dispatch.md b/collections/controller_configuration/dispatch.md new file mode 100644 index 0000000..dc2b641 --- /dev/null +++ b/collections/controller_configuration/dispatch.md @@ -0,0 +1,47 @@ +--- +layout: default +title: dispatch +parent: infra.controller_configuration +--- + +# infra.aap_configuration.dispatch + +## Description + +An Ansible Role to run all roles in the infra.aap_configuration collection. + +## Variables + +Each role has its own variables, for information on those please see each role which this role will call. This role has one key variable `gateway_dispatch_roles` and its default value is shown below: + +```yaml +gateway_dispatch_roles: + - {role: settings, var: settings_list, tags: settings} + - {role: users, var: aap_user_accounts, tags: users} + - {role: authenticators, var: authenticators_list, tags: authenticators} + - {role: authenticator_maps, var: authenticator_maps_list, tags: authenticator_maps} + - {role: http_ports, var: http_ports_list, tags: http_ports} + - {role: organizations, var: organizations_list, tags: organizations} + - {role: teams, var: platform_teams, tags: teams} + - {role: service_clusters, var: gateway_service_clusters, tags: service_clusters} + - {role: service_keys, var: service_keys_list, tags: service_keys} + - {role: service_nodes, var: gateway_service_nodes, tags: service_nodes} + - {role: services, var: gateway_services, tags: services} + - {role: routes, var: gateway_routes, tags: routes} + - {role: role_user_assignments, var: role_user_assignments_list, tags: role_user_assignments} +``` + +Note that each item has three elements: + +- `role` which is the name of the role within infra.aap_configuration +- `var` which is the variable which is used in that role. We use this to prevent the role being called if the variable is not set +- `tags` the tags which are applied to the role so it is possible to apply tags to a playbook using the dispatcher with these tags. + +It is possible to redefine this variable with a subset of roles or with different tags. In general we suggest keeping the same structure and perhaps just using a subset. + +For more information about variables, see [top-level README](../../README.md). +For more information about roles, see each roles' README (also linked in the top-level README) + +## License + +[GPL-3.0](https://github.com/redhat-cop/aap_configuration#licensing) diff --git a/collections/controller_configuration/eda_controller_tokens.md b/collections/controller_configuration/eda_controller_tokens.md new file mode 100644 index 0000000..fbdf3c2 --- /dev/null +++ b/collections/controller_configuration/eda_controller_tokens.md @@ -0,0 +1,101 @@ +--- +layout: default +title: eda_controller_tokens +parent: infra.controller_configuration +--- + +# infra.eda_configuration.controller_token + +## Description + +An Ansible Role to create User Tokens in EDA Controller. Note that tokens may only be applied to the user account accessing the API (ie. aap_username) +Note that tokens cannot be updated, only created. + +## Variables + +|Variable Name|Default Value|Required|Description|Example| +|`eda_host`|""|yes|URL to the EDA Controller (alias: `eda_hostname`)|127.0.0.1| +|`aap_username`|""|yes|Admin User on the Ansible Automation Platform Server. Either username / password or oauthtoken need to be specified.|| +|`aap_password`|""|yes|Platform Admin User's password on the EDA Controller Server. This should be stored in an Ansible Vault at vars/platform-secrets.yml or elsewhere and called from a parent playbook.|| +|`aap_validate_certs`|`False`|no|Whether or not to validate the Ansible Automation Platform Server's SSL certificate.|| +|`aap_request_timeout`|`10`|no|Specify the timeout Ansible should use in requests to the Automation Platform host.|| +|`aap_configuration_async_dir`|`null`|no|Sets the directory to write the results file for async tasks. The default value is set to `null` which uses the Ansible Default of `/root/.ansible_async/`.|| +|`aap_request_timeout`|`10`|no|Specify the timeout in seconds Ansible should use in requests to the Ansible Automation Platform host.|| +|`eda_controller_tokens`|`see below`|yes|Data structure describing your user tokens, described below.|| + +### Secure Logging Variables + +The following Variables complement each other. +If Both variables are not set, secure logging defaults to false. +The role defaults to False as normally the add project task does not include sensitive information. +eda_configuration_user_token_secure_logging defaults to the value of aap_configuration_secure_logging if it is not explicitly called. This allows for secure logging to be toggled for the entire suite of EDA Controller configuration roles with a single variable, or for the user to selectively use it. + +|Variable Name|Default Value|Required|Description| +|`eda_configuration_user_token_secure_logging`|`False`|no|Whether or not to include the sensitive Project role tasks in the log. Set this value to `True` if you will be providing your sensitive values from elsewhere.| +|`aap_configuration_secure_logging`|`False`|no|This variable enables secure logging as well, but is shared across multiple roles, see above.| + +### Asynchronous Retry Variables + +The following Variables set asynchronous retries for the role. +If neither of the retries or delay or retries are set, they will default to their respective defaults. +This allows for all items to be created, then checked that the task finishes successfully. +This also speeds up the overall role. + +|Variable Name|Default Value|Required|Description| +|`aap_configuration_async_retries`|50|no|This variable sets the number of retries to attempt for the role globally.| +|`eda_configuration_user_token_async_retries`|`aap_configuration_async_retries`|no|This variable sets the number of retries to attempt for the role.| +|`eda_configuration_async_delay`|1|no|This sets the delay between retries for the role globally.| +|`eda_configuration_user_token_async_delay`|`eda_configuration_async_delay`|no|This sets the delay between retries for the role.| + +## Data Structure + +### User Token Variables + +|Variable Name|Default Value|Required|Type|Description| +|`name`|""|yes|str|User Token name. Must be lower case containing only alphanumeric characters and underscores.| +|`description`|""|no|str|Description to use for the Project.| +|`token`|""|yes|str|The value of the token to associate with the user.| + +### Standard User Token Data Structure + +#### Yaml Example + +```yaml +eda_controller_tokens: + - name: my_default_token + description: my default user token + token: TOKEN_VALUE +``` + +## Playbook Examples + +### Standard Role Usage + +```yaml +- name: Add user token to EDA Controller + hosts: localhost + connection: local + gather_facts: false + vars: + eda_validate_certs: false + # Define following vars here, or in eda_configs/eda_auth.yml + # controller_host: ansible-eda-web-svc-test-project.example.com + # eda_token: changeme + pre_tasks: + - name: Include vars from eda_configs directory + ansible.builtin.include_vars: + dir: ./vars + extensions: ["yml"] + tags: + - always + roles: + - infra.eda_configuration.controller_tokens +``` + +## License + +[GPLv3+](https://github.com/redhat-cop/eda_configuration#licensing) + +## Author + +[Derek Waters](https://github.com/derekwaters/) diff --git a/collections/controller_configuration/eda_credentials.md b/collections/controller_configuration/eda_credentials.md new file mode 100644 index 0000000..ce1f868 --- /dev/null +++ b/collections/controller_configuration/eda_credentials.md @@ -0,0 +1,106 @@ +--- +layout: default +title: eda_credentials +parent: infra.controller_configuration +--- + +# infra.eda_configuration.credential + +## Description + +An Ansible Role to create Credentials in EDA Controller. + +## Variables + +|Variable Name|Default Value|Required|Description|Example| +|`eda_host`|""|yes|URL to the EDA Controller (alias: `eda_hostname`)|127.0.0.1| +|`aap_username`|""|yes|Admin User on the Ansible Automation Platform Server. Either username / password or oauthtoken need to be specified.|| +|`aap_password`|""|yes|Platform Admin User's password on the EDA Controller Server. This should be stored in an Ansible Vault at vars/platform-secrets.yml or elsewhere and called from a parent playbook.|| +|`aap_validate_certs`|`False`|no|Whether or not to validate the Ansible Automation Platform Server's SSL certificate.|| +|`aap_request_timeout`|`10`|no|Specify the timeout Ansible should use in requests to the Automation Platform host.|| +|`aap_configuration_async_dir`|`null`|no|Sets the directory to write the results file for async tasks. The default value is set to `null` which uses the Ansible Default of `/root/.ansible_async/`.|| +|`aap_request_timeout`|`10`|no|Specify the timeout in seconds Ansible should use in requests to the Ansible Automation Platform host.|| +|`eda_credentials`|`see below`|yes|Data structure describing your credentials, described below.|| + +### Secure Logging Variables + +The following Variables complement each other. +If Both variables are not set, secure logging defaults to false. +The role defaults to False as normally the add credential task does not include sensitive information. +eda_configuration_credential_secure_logging defaults to the value of aap_configuration_secure_logging if it is not explicitly called. This allows for secure logging to be toggled for the entire suite of EDA Controller configuration roles with a single variable, or for the user to selectively use it. + +|Variable Name|Default Value|Required|Description| +|`eda_configuration_credential_secure_logging`|`True`|no|Whether or not to include the sensitive credential role tasks in the log. Set this value to `True` if you will be providing your sensitive values from elsewhere.| +|`aap_configuration_secure_logging`|`False`|no|This variable enables secure logging as well, but is shared across multiple roles, see above.| + +### Asynchronous Retry Variables + +The following Variables set asynchronous retries for the role. +If neither of the retries or delay or retries are set, they will default to their respective defaults. +This allows for all items to be created, then checked that the task finishes successfully. +This also speeds up the overall role. + +|Variable Name|Default Value|Required|Description| +|`aap_configuration_async_retries`|50|no|This variable sets the number of retries to attempt for the role globally.| +|`eda_configuration_credential_async_retries`|`aap_configuration_async_retries`|no|This variable sets the number of retries to attempt for the role.| +|`eda_configuration_async_delay`|1|no|This sets the delay between retries for the role globally.| +|`eda_configuration_credential_async_delay`|`eda_configuration_async_delay`|no|This sets the delay between retries for the role.| + +## Data Structure + +### Credential Variables + +|Variable Name|Default Value|Required|Type|Description| +|`name`|""|yes|str|Credential name. Must be lower case containing only alphanumeric characters and underscores.| +|`new_name`|""|no|str|Setting this option will change the existing name (looked up via the name field.)| +|`description`|""|no|str|Description to use for the credential.| +|`organization`|""|no|str|Organization this Credential belongs to.| +|`inputs`|""|no|dict|Credential inputs where the keys are var names used in templating. Refer to the EDA controller documentation for example syntax.| +|`credential_type`|"GitHub Personal Access Token"|yes|str|The type of the credential.| +|`state`|`present`|no|str|Desired state of the credential.| + +### Standard Credential Data Structure + +#### Yaml Example + +```yaml +eda_credentials: + - name: my_github_user + description: my GitHub Credential + credential_type: 'GitHub Personal Access Token' + username: githubuser + secret: GITHUBTOKEN +``` + +## Playbook Examples + +### Standard Role Usage + +```yaml +- name: Add credential to EDA Controller + hosts: localhost + connection: local + gather_facts: false + vars: + eda_validate_certs: false + # Define following vars here, or in eda_configs/eda_auth.yml + # controller_host: ansible-eda-web-svc-test-credential.example.com + # eda_token: changeme + pre_tasks: + - name: Include vars from eda_configs directory + ansible.builtin.include_vars: + dir: ./vars + extensions: ["yml"] + tags: + - always + roles: + - infra.eda_configuration.credentials +``` + +## License + +[GPLv3+](https://github.com/redhat-cop/eda_configuration#licensing) + +## Author + +[Derek Waters](https://github.com/derekwaters/) diff --git a/collections/controller_configuration/eda_decision_environments.md b/collections/controller_configuration/eda_decision_environments.md new file mode 100644 index 0000000..8f8499f --- /dev/null +++ b/collections/controller_configuration/eda_decision_environments.md @@ -0,0 +1,106 @@ +--- +layout: default +title: eda_decision_environments +parent: infra.controller_configuration +--- + +# infra.eda_configuration.decision_environment + +## Description + +An Ansible Role to create Decision Environments in EDA Controller. + +## Variables + +|Variable Name|Default Value|Required|Description|Example| +|`eda_host`|""|yes|URL to the EDA Controller (alias: `eda_hostname`)|127.0.0.1| +|`aap_username`|""|yes|Admin User on the Ansible Automation Platform Server. Either username / password or oauthtoken need to be specified.|| +|`aap_password`|""|yes|Platform Admin User's password on the EDA Controller Server. This should be stored in an Ansible Vault at vars/platform-secrets.yml or elsewhere and called from a parent playbook.|| + +|`aap_validate_certs`|`False`|no|Whether or not to validate the Ansible Automation Platform Server's SSL certificate.|| +|`aap_request_timeout`|`10`|no|Specify the timeout Ansible should use in requests to the Automation Platform host.|| +|`aap_configuration_async_dir`|`null`|no|Sets the directory to write the results file for async tasks. The default value is set to `null` which uses the Ansible Default of `/root/.ansible_async/`.|| +|`aap_request_timeout`|`10`|no|Specify the timeout in seconds Ansible should use in requests to the Ansible Automation Platform host.|| +|`eda_decision_environments`|`see below`|yes|Data structure describing your decision environments, described below.|| + +### Secure Logging Variables + +The following Variables complement each other. +If Both variables are not set, secure logging defaults to false. +The role defaults to False as normally the add project task does not include sensitive information. +eda_configuration_project_secure_logging defaults to the value of aap_configuration_secure_logging if it is not explicitly called. This allows for secure logging to be toggled for the entire suite of EDA Controller configuration roles with a single variable, or for the user to selectively use it. + +|Variable Name|Default Value|Required|Description| +|`eda_configuration_project_secure_logging`|`False`|no|Whether or not to include the sensitive Project role tasks in the log. Set this value to `True` if you will be providing your sensitive values from elsewhere.| +|`aap_configuration_secure_logging`|`False`|no|This variable enables secure logging as well, but is shared across multiple roles, see above.| + +### Asynchronous Retry Variables + +The following Variables set asynchronous retries for the role. +If neither of the retries or delay or retries are set, they will default to their respective defaults. +This allows for all items to be created, then checked that the task finishes successfully. +This also speeds up the overall role. + +|Variable Name|Default Value|Required|Description| +|`aap_configuration_async_retries`|50|no|This variable sets the number of retries to attempt for the role globally.| +|`eda_configuration_project_async_retries`|`aap_configuration_async_retries`|no|This variable sets the number of retries to attempt for the role.| +|`eda_configuration_async_delay`|1|no|This sets the delay between retries for the role globally.| +|`eda_configuration_project_async_delay`|`eda_configuration_async_delay`|no|This sets the delay between retries for the role.| + +## Data Structure + +### Decision Environment Variables + +|Variable Name|Default Value|Required|Type|Description| +|`name`|""|yes|str|Decision Environment name. Must be lower case containing only alphanumeric characters and underscores.| +|`new_name`|""|no|str|Setting this option will change the existing name (looked up via the name field.)| +|`description`|""|no|str|Description to use for the Project.| +|`image_url`|""|yes|str|A URL to a a container image to use for the decision environment.| +|`credential`|""|no|str|The credential used to access the container registry holding the image.| +|`organization`|""|no|str|Organization this decision environment belongs to.| +|`state`|`present`|no|str|Desired state of the decision environment.| + +### Standard Decision Environment Data Structure + +#### Yaml Example + +```yaml +eda_decision_environments: + - name: my_default_de + description: my default decision environment + image_url: "image_registry.example.com/default-de:latest" + credential: my_credential +``` + +## Playbook Examples + +### Standard Role Usage + +```yaml +- name: Add decision environment to EDA Controller + hosts: localhost + connection: local + gather_facts: false + vars: + eda_validate_certs: false + # Define following vars here, or in eda_configs/eda_auth.yml + # controller_host: ansible-eda-web-svc-test-project.example.com + # eda_token: changeme + pre_tasks: + - name: Include vars from eda_configs directory + ansible.builtin.include_vars: + dir: ./vars + extensions: ["yml"] + tags: + - always + roles: + - infra.eda_configuration.decision_environments +``` + +## License + +[GPLv3+](https://github.com/redhat-cop/eda_configuration#licensing) + +## Author + +[Derek Waters](https://github.com/derekwaters/) diff --git a/collections/controller_configuration/eda_projects.md b/collections/controller_configuration/eda_projects.md new file mode 100644 index 0000000..511e374 --- /dev/null +++ b/collections/controller_configuration/eda_projects.md @@ -0,0 +1,107 @@ +--- +layout: default +title: eda_projects +parent: infra.controller_configuration +--- + +# infra.eda_configuration.project + +## Description + +An Ansible Role to create Projects in EDA Controller. + +## Variables + +|Variable Name|Default Value|Required|Description|Example| +|`eda_host`|""|yes|URL to the EDA Controller (alias: `eda_hostname`)|127.0.0.1| +|`aap_username`|""|yes|Admin User on the Ansible Automation Platform Server. Either username / password or oauthtoken need to be specified.|| +|`aap_password`|""|yes|Platform Admin User's password on the EDA Controller Server. This should be stored in an Ansible Vault at vars/platform-secrets.yml or elsewhere and called from a parent playbook.|| + +|`aap_validate_certs`|`False`|no|Whether or not to validate the Ansible Automation Platform Server's SSL certificate.|| +|`aap_request_timeout`|`10`|no|Specify the timeout Ansible should use in requests to the Automation Platform host.|| +|`aap_configuration_async_dir`|`null`|no|Sets the directory to write the results file for async tasks. The default value is set to `null` which uses the Ansible Default of `/root/.ansible_async/`.|| +|`aap_request_timeout`|`10`|no|Specify the timeout in seconds Ansible should use in requests to the Ansible Automation Platform host.|| +|`eda_projects`|`see below`|yes|Data structure describing your projects, described below.|| + +### Secure Logging Variables + +The following Variables compliment each other. +If Both variables are not set, secure logging defaults to false. +The role defaults to False as normally the add project task does not include sensitive information. +eda_configuration_project_secure_logging defaults to the value of aap_configuration_secure_logging if it is not explicitly called. This allows for secure logging to be toggled for the entire suite of EDA Controller configuration roles with a single variable, or for the user to selectively use it. + +|Variable Name|Default Value|Required|Description| +|`eda_configuration_project_secure_logging`|`False`|no|Whether or not to include the sensitive Project role tasks in the log. Set this value to `True` if you will be providing your sensitive values from elsewhere.| +|`aap_configuration_secure_logging`|`False`|no|This variable enables secure logging as well, but is shared across multiple roles, see above.| + +### Asynchronous Retry Variables + +The following Variables set asynchronous retries for the role. +If neither of the retries or delay or retries are set, they will default to their respective defaults. +This allows for all items to be created, then checked that the task finishes successfully. +This also speeds up the overall role. + +|Variable Name|Default Value|Required|Description| +|`aap_configuration_async_retries`|50|no|This variable sets the number of retries to attempt for the role globally.| +|`eda_configuration_project_async_retries`|`aap_configuration_async_retries`|no|This variable sets the number of retries to attempt for the role.| +|`eda_configuration_async_delay`|1|no|This sets the delay between retries for the role globally.| +|`eda_configuration_project_async_delay`|`eda_configuration_async_delay`|no|This sets the delay between retries for the role.| + +## Data Structure + +### Project Variables + +|Variable Name|Default Value|Required|Type|Description| +|`name`|""|yes|str|Project name. Must be lower case containing only alphanumeric characters and underscores.| +|`new_name`|""|no|str|Setting this option will change the existing name (looked up via the name field.)| +|`description`|""|no|str|Description to use for the Project.| +|`url`|""|yes|str|A URL to a remote archive, such as a Github Release or a build artifact stored in Artifactory and unpacks it into the project path for use. (Alias: scm_url)| +|`organization`|""|no|str|Organization this project belongs to.| +|`credential`|""|no|str|The token needed to utilize the SCM URL.| +|`state`|`present`|no|str|Desired state of the project.| + +### Standard Project Data Structure + +#### Yaml Example + +```yaml +eda_projects: + - name: my_project + description: my awesome project + url: https://github.com/ansible/ansible-rulebook.git + tls_validation: true + credential: test_token +``` + +## Playbook Examples + +### Standard Role Usage + +```yaml +- name: Add project to EDA Controller + hosts: localhost + connection: local + gather_facts: false + vars: + eda_validate_certs: false + # Define following vars here, or in eda_configs/eda_auth.yml + # controller_host: ansible-eda-web-svc-test-project.example.com + # eda_token: changeme + pre_tasks: + - name: Include vars from eda_configs directory + ansible.builtin.include_vars: + dir: ./vars + extensions: ["yml"] + tags: + - always + roles: + - infra.eda_configuration.projects +``` + +## License + +[GPLv3+](https://github.com/redhat-cop/eda_configuration#licensing) + +## Author + +[Chris Renwick](https://github.com/crenwick93/) diff --git a/collections/controller_configuration/eda_rulebook_activations.md b/collections/controller_configuration/eda_rulebook_activations.md new file mode 100644 index 0000000..1e277d0 --- /dev/null +++ b/collections/controller_configuration/eda_rulebook_activations.md @@ -0,0 +1,121 @@ +--- +layout: default +title: eda_rulebook_activations +parent: infra.controller_configuration +--- + +# infra.eda_configuration.rulebook_activation + +## Description + +An Ansible Role to create rulebook activations in EDA Controller. + +## Variables + +|Variable Name|Default Value|Required|Description|Example| +|`eda_host`|""|yes|URL to the EDA Controller (alias: `eda_hostname`)|127.0.0.1| +|`aap_username`|""|yes|Admin User on the Ansible Automation Platform Server. Either username / password or oauthtoken need to be specified.|| +|`aap_password`|""|yes|Platform Admin User's password on the EDA Controller Server. This should be stored in an Ansible Vault at vars/platform-secrets.yml or elsewhere and called from a parent playbook.|| + +|`aap_validate_certs`|`False`|no|Whether or not to validate the Ansible Automation Platform Server's SSL certificate.|| +|`aap_request_timeout`|`10`|no|Specify the timeout Ansible should use in requests to the Automation Platform host.|| +|`aap_configuration_async_dir`|`null`|no|Sets the directory to write the results file for async tasks. The default value is set to `null` which uses the Ansible Default of `/root/.ansible_async/`.|| +|`aap_request_timeout`|`10`|no|Specify the timeout in seconds Ansible should use in requests to the Ansible Automation Platform host.|| +|`eda_rulebook_activations`|`see below`|yes|Data structure describing your rulebook activations, described below.|| + +### Secure Logging Variables + +The following Variables complement each other. +If Both variables are not set, secure logging defaults to false. +The role defaults to False as normally the add project task does not include sensitive information. +eda_configuration_project_secure_logging defaults to the value of aap_configuration_secure_logging if it is not explicitly called. This allows for secure logging to be toggled for the entire suite of EDA Controller configuration roles with a single variable, or for the user to selectively use it. + +|Variable Name|Default Value|Required|Description| +|`eda_configuration_project_secure_logging`|`False`|no|Whether or not to include the sensitive Project role tasks in the log. Set this value to `True` if you will be providing your sensitive values from elsewhere.| +|`aap_configuration_secure_logging`|`False`|no|This variable enables secure logging as well, but is shared across multiple roles, see above.| + +### Asynchronous Retry Variables + +The following Variables set asynchronous retries for the role. +If neither of the retries or delay or retries are set, they will default to their respective defaults. +This allows for all items to be created, then checked that the task finishes successfully. +This also speeds up the overall role. + +|Variable Name|Default Value|Required|Description| +|`aap_configuration_async_retries`|50|no|This variable sets the number of retries to attempt for the role globally.| +|`eda_configuration_project_async_retries`|`aap_configuration_async_retries`|no|This variable sets the number of retries to attempt for the role.| +|`eda_configuration_async_delay`|1|no|This sets the delay between retries for the role globally.| +|`eda_configuration_project_async_delay`|`eda_configuration_async_delay`|no|This sets the delay between retries for the role.| + +## Data Structure + +### Rulebook activation Variables + +|Variable Name|Default Value|Required|Type|Description| +|`name`|""|yes|str|Rulebook activation name. Must be lower case containing only alphanumeric characters and underscores.| +|`description`|""|no|str|Description to use for the Activation.| +|`project`|""|no|str|Project to use for the Activation.| +|`rulebook`|""|yes|str|rulebook to use for the Activation.| +|`decision_environment`|""|yes|str|Decision_environment to use for the Activation.| +|`restart_policy`|"always"|no|str|Restart_policy to use for the Activation, choice of ["always", "never", "on-failure"]| +|`extra_vars`|""|no|str|Extra_vars to use for the Activation.| +|`awx_token`|""|no|str|The token used to authenticate to controller.| +|`enabled`|"true"|no|str|Whether the rulebook activation is automatically enabled to run.| +|`state`|`present`|no|str|Desired state of the rulebook activation.| +|`organization_name`|""|no|str|The name of the organization.| +|`eda_credentials`|""|no|list|A list of IDs for EDA credentials used by the rulebook activation.| +|`k8s_service_name`|""|no|str|The name of the Kubernetes service associated with this rulebook activation.| +|`swap_single_source`|"true"|no|bool|Allow swapping of single sources in a rulebook without name match.| +|`event_streams`|""|no|list|A list of event stream names that this rulebook activation listens to.| +|`log_level`|""|no|str|Allow setting the desired log level.| + +### Standard rulebook activation Data Structure + +#### Yaml Example + +```yaml +eda_rulebook_activations: + - name: Github Hook + description: Hook to listen for changes in GitHub + project: EDA_example + rulebook: git-hook-deploy-rules.yml + decision_environment: Automation Hub Default Decision Environment + extra_vars: + provider: github-local + repo_url: https://github.com/ansible/ansible-rulebook.git + enabled: false + state: present +``` + +## Playbook Examples + +### Standard Role Usage + +```yaml +- name: Add rulebook activation to EDA Controller + hosts: localhost + connection: local + gather_facts: false + vars: + eda_validate_certs: false + # Define following vars here, or in eda_configs/eda_auth.yml + # controller_host: ansible-eda-web-svc-test-project.example.com + # eda_token: changeme + pre_tasks: + - name: Include vars from eda_configs directory + ansible.builtin.include_vars: + dir: ./vars + extensions: ["yml"] + tags: + - always + roles: + - ../../eda_rulebook_activations +``` + +## License + +[GPLv3+](https://github.com/redhat-cop/eda_configuration#licensing) + +## Author + +[Tom Page](https://github.com/Tompage1994/) diff --git a/collections/controller_configuration/eda_users.md b/collections/controller_configuration/eda_users.md new file mode 100644 index 0000000..933be68 --- /dev/null +++ b/collections/controller_configuration/eda_users.md @@ -0,0 +1,113 @@ +--- +layout: default +title: eda_users +parent: infra.controller_configuration +--- + +# infra.eda_configuration.user + +## Description + +An Ansible Role to create users in EDA Controller. + +## Variables + +|Variable Name|Default Value|Required|Description|Example| +|`eda_host`|""|yes|URL to the EDA Controller (alias: `eda_hostname`)|127.0.0.1| +|`aap_username`|""|yes|Admin User on the Ansible Automation Platform Server. Either username / password or oauthtoken need to be specified.|| +|`aap_password`|""|yes|Platform Admin User's password on the EDA Controller Server. This should be stored in an Ansible Vault at vars/platform-secrets.yml or elsewhere and called from a parent playbook.|| +|`aap_validate_certs`|`False`|no|Whether or not to validate the Ansible Automation Platform Server's SSL certificate.|| +|`aap_request_timeout`|`10`|no|Specify the timeout Ansible should use in requests to the Automation Platform host.|| +|`aap_configuration_async_dir`|`null`|no|Sets the directory to write the results file for async tasks. The default value is set to `null` which uses the Ansible Default of `/root/.ansible_async/`.|| +|`aap_request_timeout`|`10`|no|Specify the timeout in seconds Ansible should use in requests to the Ansible Automation Platform host.|| +|`eda_users`|`see below`|yes|Data structure describing your users, described below.|| + +### Secure Logging Variables + +The following Variables compliment each other. +If Both variables are not set, secure logging defaults to false. +The role defaults to False as normally the add user task does not include sensitive information. +eda_configuration_user_secure_logging defaults to the value of aap_configuration_secure_logging if it is not explicitly called. This allows for secure logging to be toggled for the entire suite of EDA Controller configuration roles with a single variable, or for the user to selectively use it. + +|Variable Name|Default Value|Required|Description| +|`eda_configuration_user_secure_logging`|`False`|no|Whether or not to include the sensitive user role tasks in the log. Set this value to `True` if you will be providing your sensitive values from elsewhere.| +|`aap_configuration_secure_logging`|`False`|no|This variable enables secure logging as well, but is shared across multiple roles, see above.| + +### Asynchronous Retry Variables + +The following Variables set asynchronous retries for the role. +If neither of the retries or delay or retries are set, they will default to their respective defaults. +This allows for all items to be created, then checked that the task finishes successfully. +This also speeds up the overall role. + +|Variable Name|Default Value|Required|Description| +|`aap_configuration_async_retries`|50|no|This variable sets the number of retries to attempt for the role globally.| +|`eda_configuration_user_async_retries`|`aap_configuration_async_retries`|no|This variable sets the number of retries to attempt for the role.| +|`eda_configuration_async_delay`|1|no|This sets the delay between retries for the role globally.| +|`eda_configuration_user_async_delay`|`eda_configuration_async_delay`|no|This sets the delay between retries for the role.| + +## Data Structure + +### user Variables + +|Variable Name|Default Value|Required|Type|Description| +|`username`|""|yes|str|Username. Must contain only letters, numbers, and `@.+-_` characters.| +|`new_username`|""|no|str|Setting this option will change the existing username (looked up via the name field.)| +|`first_name`|""|no|str|First ame of the user.| +|`last_name`|""|no|str|Last name of the user.| +|`email`|""|no|str|User's email address.| +|`password`|""|yes|str|Password to use for the user.| +|`update_secrets`|true|no|bool|Setting true will always change password if user specifies password. Password will only change if false if other fields change.| +|`is_superuser`|""|no|bool|Make user as superuser.| +|`roles`|""|yes|list|Roles the user will have. Current acceptable values are: Viewer, Auditor, Editor, Contributor, Operator, Admin.| +|`state`|`present`|no|str|Desired state of the user.| + +### Standard user Data Structure + +#### Yaml Example + +```yaml +eda_users: +- username: jane_doe + first_name: Jane + last_name: Doe + email: jdoe@example.com + password: my_password1 + update_secrets: false + roles: + - Auditor + - Contributor +``` + +## Playbook Examples + +### Standard Role Usage + +```yaml +- name: Add user to EDA Controller + hosts: localhost + connection: local + gather_facts: false + vars: + eda_validate_certs: false + # Define following vars here, or in eda_configs/eda_auth.yml + # controller_host: ansible-eda-web-svc-test-user.example.com + # eda_token: changeme + pre_tasks: + - name: Include vars from eda_configs directory + ansible.builtin.include_vars: + dir: ./vars + extensions: ["yml"] + tags: + - always + roles: + - ../../eda_users +``` + +## License + +[GPLv3+](https://github.com/redhat-cop/eda_configuration#licensing) + +## Author + +[Tom Page](https://github.com/Tompage1994/) diff --git a/collections/controller_configuration/gateway_applications.md b/collections/controller_configuration/gateway_applications.md new file mode 100644 index 0000000..21612b8 --- /dev/null +++ b/collections/controller_configuration/gateway_applications.md @@ -0,0 +1,123 @@ +--- +layout: default +title: gateway_applications +parent: infra.controller_configuration +--- + +# Ansible Role infra.aap_configuration.applications + +## Description + +An Ansible Role to create/update/remove Applications on Ansible gateway. + +## Variables + +|Variable Name|Default Value|Required|Description|Example| +|`platform_state`|"present"|no|The state all objects will take unless overridden by object default|'absent'| +|`aap_hostname`|""|yes|URL to the Ansible Automation Platform Server.|127.0.0.1| +|`aap_validate_certs`|`True`|no|Whether or not to validate the Ansible Automation Platform Server's SSL certificate.|| +|`aap_username`|""|no|Admin User on the Ansible Automation Platform Server. Either username / password or oauthtoken need to be specified.|| +|`aap_password`|""|no|Platform Admin User's password on the Server. This should be stored in an Ansible Vault at vars/platform-secrets.yml or elsewhere and called from a parent playbook.|| +|`aap_token`|""|no|Controller Admin User's token on the Ansible Automation Platform Server. This should be stored in an Ansible Vault at or elsewhere and called from a parent playbook. Either username / password or oauthtoken need to be specified.|| +|`aap_request_timeout`|`10`|no|Specify the timeout in seconds Ansible should use in requests to the Ansible Automation Platform host.|| +|`aap_applications`|`see below`|yes|Data structure describing your aap_applications Described below.|| + +### Enforcing defaults + +The following Variables compliment each other. +If Both variables are not set, enforcing default values is not done. +Enabling these variables enforce default values on options that are optional in the controller API. +This should be enabled to enforce configuration and prevent configuration drift. It is recomended to be enabled, however it is not enforced by default. + +Enabling this will enforce configurtion without specifying every option in the configuration files. + +'aap_applications_enforce_defaults' defaults to the value of 'aap_configuration_enforce_defaults' if it is not explicitly called. This allows for enforced defaults to be toggled for the entire suite of controller configuration roles with a single variable, or for the user to selectively use it. + +|Variable Name|Default Value|Required|Description| +|`aap_applications_enforce_defaults`|`False`|no|Whether or not to enforce default option values on only the applications role| +|`aap_configuration_enforce_defaults`|`False`|no|This variable enables enforced default values as well, but is shared globally.| + +### Secure Logging Variables + +The following Variables compliment each other. +If Both variables are not set, secure logging defaults to false. +The role defaults to False as normally the add ee_registry task does not include sensitive information. +aap_applications_secure_logging defaults to the value of aap_configuration_secure_logging if it is not explicitly called. This allows for secure logging to be toggled for the entire suite of automation hub configuration roles with a single variable, or for the user to selectively use it. + +|Variable Name|Default Value|Required|Description| +|`aap_applications_secure_logging`|`False`|no|Whether or not to include the sensitive Registry role tasks in the log. Set this value to `True` if you will be providing your sensitive values from elsewhere.| +|`aap_configuration_secure_logging`|`False`|no|This variable enables secure logging as well, but is shared across multiple roles, see above.| + +### Asynchronous Retry Variables + +The following Variables set asynchronous retries for the role. +If neither of the retries or delay or retries are set, they will default to their respective defaults. +This allows for all items to be created, then checked that the task finishes successfully. +This also speeds up the overall role. + +|Variable Name|Default Value|Required|Description| +|`aap_configuration_async_retries`|50|no|This variable sets the number of retries to attempt for the role globally.| +|`aap_applications_async_retries`|`aap_configuration_async_retries`|no|This variable sets the number of retries to attempt for the role.| +|`aap_configuration_async_delay`|1|no|This sets the delay between retries for the role globally.| +|`aap_applications_async_delay`|`aap_configuration_async_delay`|no|This sets the delay between retries for the role.| +|`aap_configuration_loop_delay`|1000|no|This variable sets the loop_delay for the role globally.| +|`aap_applications_loop_delay`|`aap_configuration_loop_delay`|no|This variable sets the loop_delay for the role.| +|`aap_configuration_async_dir`|`null`|no|Sets the directory to write the results file for async tasks. The default value is set to `null` which uses the Ansible Default of `/root/.ansible_async/`.| + +## Data Structure + +### Application Arguments + +Options for the `aap_applications` variable: + +| Variable Name | Default Value | Required | Type | Description | +| `name` | N/A | yes | str | Name of application | +| `new_name` | N/A | no | str | Setting this option will change the existing name (looked up via the name field). | +| `organization` | N/A | yes | str | Name of the organization for the application | +| `new_organization` | N/A | no | str | The name or ID referencing newly associated organization | +| `algorithm` | N/A | no | str | The OIDC token signing algorithm for this application. Choices: ["", "RS256", "HS256"] | +| `description` | N/A | no | str | Description to use for the application. | +| `authorization_grant_type` | N/A | yes | str | Grant type for tokens in this application, Choices: ["password", "authorization-code"] | +| `client_type` | N/A | yes | str | Application client type. Choices: ["confidential", "public"] | +| `redirect_uris` | "" | no | str | Allowed urls list, space separated. Required with "authorization-code" grant type | +| `skip_authorization` | N/A(`false` by API) | yes | bool | Set True to skip authorization step for completely trusted applications. | +| `post_logout_redirect_uris` | "" | no | str | Allowed Post Logout URIs list, space separated. | +| `user` | "" | no | str | The user who owns this application. | +| `state` | `present` | no | str | Desired state of the application. | + +### Standard Application Data Structure + +#### Json Example + +```json + { + "aap_applications": [ + { + "name": "gateway Config Default Application", + "description": "Generic application, which can be used for oauth tokens", + "organization": "Default", + "state": "present", + "client_type": "confidential", + "authorization_grant_type": "password" + } + ] +} +``` + +#### Yaml Example + +File name: `data/aap_applications.yml` + +```yaml +aap_applications: +- name: "gateway Config Default Application" + description: "Generic application, which can be used for oauth tokens" + organization: "Default" + state: "present" + client_type: "confidential" + authorization_grant_type: "password" +``` + +## License + +[GPL-3.0](https://github.com/redhat-cop/aap_configuration#licensing) diff --git a/collections/controller_configuration/gateway_authenticator_maps.md b/collections/controller_configuration/gateway_authenticator_maps.md new file mode 100644 index 0000000..1a490ac --- /dev/null +++ b/collections/controller_configuration/gateway_authenticator_maps.md @@ -0,0 +1,163 @@ +--- +layout: default +title: gateway_authenticator_maps +parent: infra.controller_configuration +--- + +# Ansible Role infra.aap_configuration.authenticator_maps + +## Description + +An Ansible Role to add Authenticator Maps on Ansible Automation gateway. + +## Variables + +|Variable Name|Default Value|Required|Description|Example| +|`platform_state`|"present"|no|The state all objects will take unless overridden by object default|'absent'| +|`aap_hostname`|""|yes|URL to the Ansible Automation Platform Server.|127.0.0.1| +|`aap_validate_certs`|`True`|no|Whether or not to validate the Ansible Automation Platform Server's SSL certificate.|| +|`aap_username`|""|no|Admin User on the Ansible Automation Platform Server. Either username / password or oauthtoken need to be specified.|| +|`aap_password`|""|no|Platform Admin User's password on the Server. This should be stored in an Ansible Vault at vars/platform-secrets.yml or elsewhere and called from a parent playbook.|| +|`aap_token`|""|no|Controller Admin User's token on the Ansible Automation Platform Server. This should be stored in an Ansible Vault at or elsewhere and called from a parent playbook. Either username / password or oauthtoken need to be specified.|| +|`aap_request_timeout`|`10`|no|Specify the timeout in seconds Ansible should use in requests to the Ansible Automation Platform host.|| +|`gateway_authenticator_maps`|`see below`|yes|Data structure describing your gateway_authenticator_maps Described below.|| + +### Secure Logging Variables + +The following Variables compliment each other. +If Both variables are not set, secure logging defaults to false. +The role defaults to False as normally the add ee_registry task does not include sensitive information. +gateway_authenticator_maps_secure_logging defaults to the value of aap_configuration_secure_logging if it is not explicitly called. This allows for secure logging to be toggled for the entire suite of automation hub configuration roles with a single variable, or for the user to selectively use it. + +|Variable Name|Default Value|Required|Description| +|`gateway_authenticator_maps_secure_logging`|`False`|no|Whether or not to include the sensitive Registry role tasks in the log. Set this value to `True` if you will be providing your sensitive values from elsewhere.| +|`aap_configuration_secure_logging`|`False`|no|This variable enables secure logging as well, but is shared across multiple roles, see above.| + +### Asynchronous Retry Variables + +The following Variables set asynchronous retries for the role. +If neither of the retries or delay or retries are set, they will default to their respective defaults. +This allows for all items to be created, then checked that the task finishes successfully. +This also speeds up the overall role. + +|Variable Name|Default Value|Required|Description| +|`aap_configuration_async_retries`|50|no|This variable sets the number of retries to attempt for the role globally.| +|`gateway_authenticator_maps_async_retries`|`aap_configuration_async_retries`|no|This variable sets the number of retries to attempt for the role.| +|`aap_configuration_async_delay`|1|no|This sets the delay between retries for the role globally.| +|`gateway_authenticator_maps_async_delay`|`aap_configuration_async_delay`|no|This sets the delay between retries for the role.| +|`aap_configuration_loop_delay`|1000|no|This variable sets the loop_delay for the role globally.| +|`gateway_authenticator_maps_loop_delay`|`aap_configuration_loop_delay`|no|This variable sets the loop_delay for the role.| +|`aap_configuration_async_dir`|`null`|no|Sets the directory to write the results file for async tasks. The default value is set to `null` which uses the Ansible Default of `/root/.ansible_async/`.| + +## Data Structure + +### Authenticator Map Arguments + +Options for the `authenticator_maps_list` variable: + +| Variable Name | Default Value | Required | Type | Description | +| `name` | N/A | yes | str | The name of the resource | +| `new_name` | N/A | no | str | Setting this option will change the existing name (looked up via the name field) | +| `authenticator` | N/A | yes | str | The name or ID referencing the [Authenticator](../gateway_authenticators/README.md) | +| `new_authenticator` | N/A | no | str | The name or ID referencing newly associated authenticator | +| `revoke` | `false` | no | bool | If a user does not meet this rule should we revoke the permission | +| `map_type` | `team` | no | str | What does the map work on, a team, a user flag or is this an allow rule. choices: ["allow", "is_superuser", "team", "organization", "role"] | +| `role` | N/A | no | str | The name of RBAC Role Definition to be used for this map | +| `team` | N/A | no | str | A team name this rule works on | +| `organization` | N/A | no | str | An organization name this rule works on | +| `triggers` | `{}` | no | dict | Trigger information for this rule | +| `order` | N/A(`0` by API) | no | int | The order in which this rule should be processed, smaller numbers are of higher precedence | +| `state` | `present` | no | str | Desired state of the resource. | + +### Unique value + +- [`name`, `authenticator`] + +## Usage + +### Json Example + +- Creates 1 authenticator map with map_type == 'organization' => requires value for "organization" +- Creates 1 authenticator map with map_type == 'team' => requires values for "team" and "organization" + +```json +{ + "gateway_authenticator_maps": [ + { + "name": "AMap-1", + "authenticator": "Authenticator-1", + "revoke": false, + "map_type": "organization", + "organization": "Organization 1", + "triggers": { + "always": {}, + "never": {} + }, + "order": 10 + }, + { + "name": "AMap-2", + "authenticator": "Authenticator-2", + "map_type": "team", + "team": "Team 1", + "organization": "Organization 1", + "role": "Team Member", + "triggers": { + "never": {} + } + } + ] +} +``` + +### Yaml Example + +- Creates Authenticator Map with examples of triggers structure +- Renames Authenticator Map and changes Authenticator + +```yaml +gateway_authenticator_maps: +- name: AuthMap 1 + authenticator: Auth 1 + revoke: true + map_type: organization + organization: Organization 1 + role: Organization Admin + triggers: + always: { } + never: { } + groups: + has_or: + - has_or_11 + - has_or_22 + has_and: + - has_and_1 + - has_and_22 + attributes: + join_condition: "or" + attr_1: + contains: aaa + matches: "bbb" + ends_with: "ccc" + attr_2: + in: + - abc1 + - abc2 + - abc3 +- name: "AuthMapX" + new_name: "Authenticator Map X" + authenticator: "Auth" + new_authenticator: "Auth 2" +``` + +### Run Playbook + +File name: [manage_data.yml](../../README.md#example-ansible-playbook) can be found in the top-level README. + +```shell +ansible-playbook manage_data.yml -e @data/gateway_authenticator_maps.yml +``` + +## License + +[GPL-3.0](https://github.com/redhat-cop/aap_configuration#licensing) diff --git a/collections/controller_configuration/gateway_authenticators.md b/collections/controller_configuration/gateway_authenticators.md new file mode 100644 index 0000000..fb2e724 --- /dev/null +++ b/collections/controller_configuration/gateway_authenticators.md @@ -0,0 +1,132 @@ +--- +layout: default +title: gateway_authenticators +parent: infra.controller_configuration +--- + +# Ansible Role infra.aap_configuration.authenticators + +## Description + +An Ansible Role to add Authenticators on Ansible Automation gateway. + +## Variables + +|Variable Name|Default Value|Required|Description|Example| +|`platform_state`|"present"|no|The state all objects will take unless overridden by object default|'absent'| +|`aap_hostname`|""|yes|URL to the Ansible Automation Platform Server.|127.0.0.1| +|`aap_validate_certs`|`True`|no|Whether or not to validate the Ansible Automation Platform Server's SSL certificate.|| +|`aap_username`|""|no|Admin User on the Ansible Automation Platform Server. Either username / password or oauthtoken need to be specified.|| +|`aap_password`|""|no|Platform Admin User's password on the Server. This should be stored in an Ansible Vault at vars/platform-secrets.yml or elsewhere and called from a parent playbook.|| +|`aap_token`|""|no|Controller Admin User's token on the Ansible Automation Platform Server. This should be stored in an Ansible Vault at or elsewhere and called from a parent playbook. Either username / password or oauthtoken need to be specified.|| +|`aap_request_timeout`|`10`|no|Specify the timeout in seconds Ansible should use in requests to the Ansible Automation Platform host.|| +|`gateway_authenticators`|`see below`|yes|Data structure describing your gateway_authenticators Described below.|| + +### Secure Logging Variables + +The following Variables compliment each other. +If Both variables are not set, secure logging defaults to false. +The role defaults to False as normally the add ee_registry task does not include sensitive information. +gateway_authenticators_secure_logging defaults to the value of aap_configuration_secure_logging if it is not explicitly called. This allows for secure logging to be toggled for the entire suite of automation hub configuration roles with a single variable, or for the user to selectively use it. + +|Variable Name|Default Value|Required|Description| +|`gateway_authenticators_secure_logging`|`False`|no|Whether or not to include the sensitive Registry role tasks in the log. Set this value to `True` if you will be providing your sensitive values from elsewhere.| +|`aap_configuration_secure_logging`|`False`|no|This variable enables secure logging as well, but is shared across multiple roles, see above.| + +### Asynchronous Retry Variables + +The following Variables set asynchronous retries for the role. +If neither of the retries or delay or retries are set, they will default to their respective defaults. +This allows for all items to be created, then checked that the task finishes successfully. +This also speeds up the overall role. + +|Variable Name|Default Value|Required|Description| +|`aap_configuration_async_retries`|50|no|This variable sets the number of retries to attempt for the role globally.| +|`gateway_authenticators_async_retries`|`aap_configuration_async_retries`|no|This variable sets the number of retries to attempt for the role.| +|`aap_configuration_async_delay`|1|no|This sets the delay between retries for the role globally.| +|`gateway_authenticators_async_delay`|`aap_configuration_async_delay`|no|This sets the delay between retries for the role.| +|`aap_configuration_loop_delay`|1000|no|This variable sets the loop_delay for the role globally.| +|`gateway_authenticators_loop_delay`|`aap_configuration_loop_delay`|no|This variable sets the loop_delay for the role.| +|`aap_configuration_async_dir`|`null`|no|Sets the directory to write the results file for async tasks. The default value is set to `null` which uses the Ansible Default of `/root/.ansible_async/`.| + +## Data Structure + +### Authenticator Arguments + +Options for the `authenticators_list` variable: + +| Variable Name | Default Value | Required | Type | Description | +| `name` | N/A | yes | str | The name of the resource | +| `new_name` | N/A | no | str | Setting this option will change the existing name (looked up via the name field) | +| `slug` | N/A | no | str | An immutable identifier for the authenticator | +| `enabled` | N/A(`false` by API) | no | bool | Enable/Disable the authenticator | +| `create_objects` | N/A(`true` by API) | no | bool | Allow authenticator to create objects (users, teams, organizations) | +| `remove_users` | N/A(`true` by API) | no | bool | When a user authenticates from this source should they be removed from any other groups they were previously added to | +| `configuration` | N/A | no | dict | The required configuration for this source (dict keys specified by the module in 'type') | +| `type` | N/A | no | str | The type of authentication service this is. Can be one of the modules: `ansible_base.authentication.authenticator_plugins.*` | +| `order` | N/A (`1` by API) | no | int | The order in which an authenticator will be tried. This only pertains to username/password authenticators | +| `state` | `present` | no | str | Desired state of the resource. | + +### Unique value + +- `name` +- `slug` (can't be used as an identificator) + +## Usage + +### Json Example + +- Creates local authenticator +- Renames authenticator + +```json +{ + "gateway_authenticators": [ + { + "name": "local authenticator", + "slug": "local-authenticator", + "type": "ansible_base.authentication.authenticator_plugins.local", + "enabled": true, + "configuration": {} + }, + { + "name": "github authenticator", + "new_name": "New GitHub Authenticator" + } + ] +} +``` + +### Yaml Example + +- Deletes 1 authenticator +- Creates an AzureAD authenticator with configuration provided by the `ansible_base.authentication.authenticator_plugins.azuread` module + - configuration class can be found in [in ansible-django-base](https://github.com/ansible/django-ansible-base/tree/devel/ansible_base/authentication/authenticator_plugins) + +File name: `data/gateway_authenticators.yml` + +```yaml +gateway_authenticators: +- name: "Deprecated Authenticator" + state: absent +- name: Auth AzureAD + type: 'ansible_base.authentication.authenticator_plugins.azuread' + slug: authenticator-azuread + enabled: true + configuration: + CALLBACK_URL: 'https://127.0.0.1' + KEY: 'oidc-key' + SECRET: 'oidc-secret' +``` + +### Run Playbook + +File name: [manage_data.yml](../../README.md#example-ansible-playbook) can be found in the top-level README. + +```shell +ansible-playbook manage_data.yml -e @data/gateway_authenticators.yml +``` + +## License + +[GPL-3.0](https://github.com/redhat-cop/aap_configuration#licensing) diff --git a/collections/controller_configuration/gateway_http_ports.md b/collections/controller_configuration/gateway_http_ports.md new file mode 100644 index 0000000..d5995c3 --- /dev/null +++ b/collections/controller_configuration/gateway_http_ports.md @@ -0,0 +1,113 @@ +--- +layout: default +title: gateway_http_ports +parent: infra.controller_configuration +--- + +# Ansible Role infra.aap_configuration.http_ports + +## Description + +An Ansible Role to add proxy Http Ports on Ansible Automation gateway. + +## Variables + +|Variable Name|Default Value|Required|Description|Example| +|`platform_state`|"present"|no|The state all objects will take unless overridden by object default|'absent'| +|`aap_hostname`|""|yes|URL to the Ansible Automation Platform Server.|127.0.0.1| +|`aap_validate_certs`|`True`|no|Whether or not to validate the Ansible Automation Platform Server's SSL certificate.|| +|`aap_username`|""|no|Admin User on the Ansible Automation Platform Server. Either username / password or oauthtoken need to be specified.|| +|`aap_password`|""|no|Platform Admin User's password on the Server. This should be stored in an Ansible Vault at vars/platform-secrets.yml or elsewhere and called from a parent playbook.|| +|`aap_token`|""|no|Controller Admin User's token on the Ansible Automation Platform Server. This should be stored in an Ansible Vault at or elsewhere and called from a parent playbook. Either username / password or oauthtoken need to be specified.|| +|`aap_request_timeout`|`10`|no|Specify the timeout in seconds Ansible should use in requests to the Ansible Automation Platform host.|| +|`gateway_http_ports`|`see below`|yes|Data structure describing your http_ports entries Described below.|| + +### Secure Logging Variables + +The following Variables compliment each other. +If Both variables are not set, secure logging defaults to false. +The role defaults to False as normally the add ee_registry task does not include sensitive information. +gateway_http_ports_secure_logging defaults to the value of aap_configuration_secure_logging if it is not explicitly called. This allows for secure logging to be toggled for the entire suite of automation hub configuration roles with a single variable, or for the user to selectively use it. + +|Variable Name|Default Value|Required|Description| +|`gateway_http_ports_secure_logging`|`False`|no|Whether or not to include the sensitive Registry role tasks in the log. Set this value to `True` if you will be providing your sensitive values from elsewhere.| +|`aap_configuration_secure_logging`|`False`|no|This variable enables secure logging as well, but is shared across multiple roles, see above.| + +### Asynchronous Retry Variables + +The following Variables set asynchronous retries for the role. +If neither of the retries or delay or retries are set, they will default to their respective defaults. +This allows for all items to be created, then checked that the task finishes successfully. +This also speeds up the overall role. + +|Variable Name|Default Value|Required|Description| +|`aap_configuration_async_retries`|50|no|This variable sets the number of retries to attempt for the role globally.| +|`gateway_http_ports_async_retries`|`aap_configuration_async_retries`|no|This variable sets the number of retries to attempt for the role.| +|`aap_configuration_async_delay`|1|no|This sets the delay between retries for the role globally.| +|`gateway_http_ports_hosts_async_delay`|`aap_configuration_async_delay`|no|This sets the delay between retries for the role.| +|`aap_configuration_loop_delay`|1000|no|This variable sets the loop_delay for the role globally.| +|`gateway_http_ports_loop_delay`|`aap_configuration_loop_delay`|no|This variable sets the loop_delay for the role.| +|`aap_configuration_async_dir`|`null`|no|Sets the directory to write the results file for async tasks. The default value is set to `null` which uses the Ansible Default of `/root/.ansible_async/`.| + +## Data Structure + +### Http Port Arguments + +Options for the `http_ports_list` variable: + +| Variable Name | Default Value | Required | Type | Description | +| `name` | N/A | yes | str | The name of the resource | +| `new_name` | N/A | no | str | Setting this option will change the existing name (looked up via the name field) | +| `number` | N/A | no | int | Port number, must be unique | +| `use_https` | `false` | no | bool | Secure this port with HTTPS | +| `is_api_port` | `false` | no | bool | If true, port is used for serving remote AAP APIs. Only one can be set to True | +| `state` | `present` | no | str | Desired state of the resource. | + +**Unique value:** + +- `name` +- `number` + +## Usage + +### Json Example + +- Create or update the proxy http port 443, renames it to "Proxy API Port" + +```json +{ + "gateway_http_ports": [ + { + "name": "API port", + "new_name": "Proxy API port", + "number": 443, + "is_api_port": true, + "use_https": true + } + ] +} +``` + +### Yaml Example + +- Delete port (if exists) 8001 +- Create port (if not exists) 8002 +- Create or update port 8003 + +File name: `data/gateway_http_ports.yml` + +```yaml +gateway_http_ports: +- name: "Service Port 8001" + number: 8001 + state: absent +- name: "Reserved port" + number: 8002 +- name: "Backup port" + number: 8003 + use_https: true +``` + +## License + +[GPL-3.0](https://github.com/redhat-cop/aap_configuration#licensing) diff --git a/collections/controller_configuration/gateway_organizations.md b/collections/controller_configuration/gateway_organizations.md new file mode 100644 index 0000000..2a15525 --- /dev/null +++ b/collections/controller_configuration/gateway_organizations.md @@ -0,0 +1,118 @@ +--- +layout: default +title: gateway_organizations +parent: infra.controller_configuration +--- + +# Ansible Role infra.aap_configuration.organizations + +## Description + +An Ansible Role to add Organizations on Ansible Automation gateway. + +## Variables + +|Variable Name|Default Value|Required|Description|Example| +|`platform_state`|"present"|no|The state all objects will take unless overridden by object default|'absent'| +|`aap_hostname`|""|yes|URL to the Ansible Automation Platform Server.|127.0.0.1| +|`aap_validate_certs`|`True`|no|Whether or not to validate the Ansible Automation Platform Server's SSL certificate.|| +|`aap_username`|""|no|Admin User on the Ansible Automation Platform Server. Either username / password or oauthtoken need to be specified.|| +|`aap_password`|""|no|Platform Admin User's password on the Server. This should be stored in an Ansible Vault at vars/platform-secrets.yml or elsewhere and called from a parent playbook.|| +|`aap_token`|""|no|Controller Admin User's token on the Ansible Automation Platform Server. This should be stored in an Ansible Vault at or elsewhere and called from a parent playbook. Either username / password or oauthtoken need to be specified.|| +|`aap_request_timeout`|`10`|no|Specify the timeout in seconds Ansible should use in requests to the Ansible Automation Platform host.|| +|`aap_organizations`|`see below`|yes|Data structure describing your organizations Described below.|| + +### Secure Logging Variables + +The following Variables compliment each other. +If Both variables are not set, secure logging defaults to false. +The role defaults to False as normally the add ee_registry task does not include sensitive information. +aap_organizations_secure_logging defaults to the value of aap_configuration_secure_logging if it is not explicitly called. This allows for secure logging to be toggled for the entire suite of automation hub configuration roles with a single variable, or for the user to selectively use it. + +|Variable Name|Default Value|Required|Description| +|`aap_organizations_secure_logging`|`False`|no|Whether or not to include the sensitive Registry role tasks in the log. Set this value to `True` if you will be providing your sensitive values from elsewhere.| +|`aap_configuration_secure_logging`|`False`|no|This variable enables secure logging as well, but is shared across multiple roles, see above.| + +### Asynchronous Retry Variables + +The following Variables set asynchronous retries for the role. +If neither of the retries or delay or retries are set, they will default to their respective defaults. +This allows for all items to be created, then checked that the task finishes successfully. +This also speeds up the overall role. + +|Variable Name|Default Value|Required|Description| +|`aap_configuration_async_retries`|50|no|This variable sets the number of retries to attempt for the role globally.| +|`aap_organizations_async_retries`|`aap_configuration_async_retries`|no|This variable sets the number of retries to attempt for the role.| +|`aap_configuration_async_delay`|1|no|This sets the delay between retries for the role globally.| +|`aap_organizations_async_delay`|`aap_configuration_async_delay`|no|This sets the delay between retries for the role.| +|`aap_configuration_loop_delay`|1000|no|This variable sets the loop_delay for the role globally.| +|`aap_organizations_loop_delay`|`aap_configuration_loop_delay`|no|This variable sets the loop_delay for the role.| +|`aap_configuration_async_dir`|`null`|no|Sets the directory to write the results file for async tasks. The default value is set to `null` which uses the Ansible Default of `/root/.ansible_async/`.| + +## Data Structure + +### Organization Arguments + +Options for the `aap_organizations` variable: + +| Variable Name | Default Value | Required | Type | Description | +| `name` | N/A | yes | str | The name of the resource | +| `new_name` | N/A | no | str | Setting this option will change the existing name (looked up via the name field) | +| `description` | N/A | no | str | Description of the organization | +| `state` | `present` | no | str | Desired state of the resource. | + +### Unique value + +- `name` + +## Usage + +### Json Example + +- Create 2 Organizations + +```json +{ + "aap_organizations": [ + { + "name": "Org 1", + "description": "First Organization" + }, + { + "name": "Org 2" + } + ] +} +``` + +### Yaml Example + +- Check that "Deprecated Org" doesn't exist +- Check that Org 1 exists +- Get or create Org 2 +- Rename Org 3 + +File name: `data/aap_organizations.yml` + +```yaml +aap_organizations: +- name: "Deprecated Org" + state: absent +- name: Org 1 + state: exists +- name: Org 2 +- name: Org 3 + new_name: Organization 3 +``` + +### Run Playbook + +File name: [manage_data.yml](../../README.md#example-ansible-playbook) can be found in the top-level README. + +```shell +ansible-playbook manage_data.yml -e @data/aap_organizations.yml +``` + +## License + +[GPL-3.0](https://github.com/redhat-cop/aap_configuration#licensing) diff --git a/collections/controller_configuration/gateway_role_user_assignments.md b/collections/controller_configuration/gateway_role_user_assignments.md new file mode 100644 index 0000000..e845e74 --- /dev/null +++ b/collections/controller_configuration/gateway_role_user_assignments.md @@ -0,0 +1,111 @@ +--- +layout: default +title: gateway_role_user_assignments +parent: infra.controller_configuration +--- + +# Ansible Role infra.aap_configuration.role_user_assignments + +## Description + +An Ansible Role to give a user permission to a resource like an organization. + +## Variables + +|Variable Name|Default Value|Required|Description|Example| +|`platform_state`|"present"|no|The state all objects will take unless overridden by object default|'absent'| +|`aap_hostname`|""|yes|URL to the Ansible Automation Platform Server.|127.0.0.1| +|`aap_validate_certs`|`True`|no|Whether or not to validate the Ansible Automation Platform Server's SSL certificate.|| +|`aap_username`|""|no|Admin User on the Ansible Automation Platform Server. Either username / password or oauthtoken need to be specified.|| +|`aap_password`|""|no|Platform Admin User's password on the Server. This should be stored in an Ansible Vault at vars/platform-secrets.yml or elsewhere and called from a parent playbook.|| +|`aap_token`|""|no|Controller Admin User's token on the Ansible Automation Platform Server. This should be stored in an Ansible Vault at or elsewhere and called from a parent playbook. Either username / password or oauthtoken need to be specified.|| +|`aap_request_timeout`|`10`|no|Specify the timeout in seconds Ansible should use in requests to the Ansible Automation Platform host.|| +|`gateway_role_user_assignments`|`see below`|yes|Data structure describing your gateway_role_user_assignment Described below.|| + +### Secure Logging Variables + +The following Variables compliment each other. +If Both variables are not set, secure logging defaults to false. +The role defaults to False as normally the add ee_registry task does not include sensitive information. +gateway_role_user_assignments_secure_logging defaults to the value of aap_configuration_secure_logging if it is not explicitly called. This allows for secure logging to be toggled for the entire suite of automation hub configuration roles with a single variable, or for the user to selectively use it. + +|Variable Name|Default Value|Required|Description| +|`gateway_role_user_assignments_secure_logging`|`False`|no|Whether or not to include the sensitive Registry role tasks in the log. Set this value to `True` if you will be providing your sensitive values from elsewhere.| +|`aap_configuration_secure_logging`|`False`|no|This variable enables secure logging as well, but is shared across multiple roles, see above.| + +### Asynchronous Retry Variables + +The following Variables set asynchronous retries for the role. +If neither of the retries or delay or retries are set, they will default to their respective defaults. +This allows for all items to be created, then checked that the task finishes successfully. +This also speeds up the overall role. + +|Variable Name|Default Value|Required|Description| +|`aap_configuration_async_retries`|50|no|This variable sets the number of retries to attempt for the role globally.| +|`gateway_role_user_assignments_async_retries`|`aap_configuration_async_retries`|no|This variable sets the number of retries to attempt for the role.| +|`aap_configuration_async_delay`|1|no|This sets the delay between retries for the role globally.| +|`gateway_role_user_assignments_async_delay`|`aap_configuration_async_delay`|no|This sets the delay between retries for the role.| +|`aap_configuration_loop_delay`|1000|no|This variable sets the loop_delay for the role globally.| +|`gateway_role_user_assignments_loop_delay`|`aap_configuration_loop_delay`|no|This variable sets the loop_delay for the role.| +|`aap_configuration_async_dir`|`null`|no|Sets the directory to write the results file for async tasks. The default value is set to `null` which uses the Ansible Default of `/root/.ansible_async/`.| + +## Data Structure + +### Role User Assignments Arguments + +Options for the `role_user_assignments` variable: + +| Variable Name | Default Value | Required | Type | Description | +| `role_definition` | N/A | yes | str | The name or id of the role definition to assign to the user. | +| `user` | N/A | no | str | The username or id of the user to assign to the object. | +| `user_ansible_id` | N/A | no | str | Resource id of the user who will receive permissions from this assignment. Alternative to user field. | +| `object_id` | N/A | no | int | Primary key of the object this assignment applies to. | +| `object_ansible_id` | N/A | no | str | Resource id of the object this role applies to. Alternative to the object_id field. | +| `state` | `present` | no | str | Desired state of the resource. | + +**Unique value:** + +- [`user`, `object_id`] (`*_ansible_id` alternatives can be provided) + +## Usage + +### Json Example + +- Assign Organization Member role (object_id is an organization with ID 1) + +```json +{ + "gateway_role_user_assignments": [ + { + "role_definition": "Organization Member", + "user": "Bob", + "object_id": "1", + } + ] +} +``` + +### Yaml Example + +- Assign Team Admin role (object_id is a team with ID 10) + +File name: `data/gateway_role_user_assignments.yml` + +```yaml +gateway_role_user_assignments: +- role_definition: Team Admin + user: 1 + object_id: 10 +``` + +### Run Playbook + +File name: [manage_data.yml](../../README.md#example-ansible-playbook) can be found in the top-level README. + +```shell +ansible-playbook manage_data.yml -e @data/gateway_role_user_assignments.yml +``` + +## License + +[GPL-3.0](https://github.com/redhat-cop/aap_configuration#licensing) diff --git a/collections/controller_configuration/gateway_routes.md b/collections/controller_configuration/gateway_routes.md new file mode 100644 index 0000000..3bb45aa --- /dev/null +++ b/collections/controller_configuration/gateway_routes.md @@ -0,0 +1,134 @@ +--- +layout: default +title: gateway_routes +parent: infra.controller_configuration +--- + +# Ansible Role infra.aap_configuration.routes + +## Description + +An Ansible Role to configure gateway non-API Routes to services (controller, hub,...) on Ansible Automation gateway. +They define http port and path (**not** starting with prefix /api/) used in gateway and +http port and path in the destination service (gateway, controller, hub, eda). + +## Variables + +|Variable Name|Default Value|Required|Description|Example| +|`platform_state`|"present"|no|The state all objects will take unless overridden by object default|'absent'| +|`aap_hostname`|""|yes|URL to the Ansible Automation Platform Server.|127.0.0.1| +|`aap_validate_certs`|`True`|no|Whether or not to validate the Ansible Automation Platform Server's SSL certificate.|| +|`aap_username`|""|no|Admin User on the Ansible Automation Platform Server. Either username / password or oauthtoken need to be specified.|| +|`aap_password`|""|no|Platform Admin User's password on the Server. This should be stored in an Ansible Vault at vars/platform-secrets.yml or elsewhere and called from a parent playbook.|| +|`aap_token`|""|no|Controller Admin User's token on the Ansible Automation Platform Server. This should be stored in an Ansible Vault at or elsewhere and called from a parent playbook. Either username / password or oauthtoken need to be specified.|| +|`aap_request_timeout`|`10`|no|Specify the timeout in seconds Ansible should use in requests to the Ansible Automation Platform host.|| +|`gateway_routes`|`see below`|yes|Data structure describing your gateway_routes Described below.|| + +### Secure Logging Variables + +The following Variables compliment each other. +If Both variables are not set, secure logging defaults to false. +The role defaults to False as normally the add ee_registry task does not include sensitive information. +gateway_routes_secure_logging defaults to the value of aap_configuration_secure_logging if it is not explicitly called. This allows for secure logging to be toggled for the entire suite of automation hub configuration roles with a single variable, or for the user to selectively use it. + +|Variable Name|Default Value|Required|Description| +|`gateway_routes_secure_logging`|`False`|no|Whether or not to include the sensitive Registry role tasks in the log. Set this value to `True` if you will be providing your sensitive values from elsewhere.| +|`aap_configuration_secure_logging`|`False`|no|This variable enables secure logging as well, but is shared across multiple roles, see above.| + +### Asynchronous Retry Variables + +The following Variables set asynchronous retries for the role. +If neither of the retries or delay or retries are set, they will default to their respective defaults. +This allows for all items to be created, then checked that the task finishes successfully. +This also speeds up the overall role. + +|Variable Name|Default Value|Required|Description| +|`aap_configuration_async_retries`|50|no|This variable sets the number of retries to attempt for the role globally.| +|`gateway_routes_async_retries`|`aap_configuration_async_retries`|no|This variable sets the number of retries to attempt for the role.| +|`aap_configuration_async_delay`|1|no|This sets the delay between retries for the role globally.| +|`gateway_routes_async_delay`|`aap_configuration_async_delay`|no|This sets the delay between retries for the role.| +|`aap_configuration_loop_delay`|1000|no|This variable sets the loop_delay for the role globally.| +|`gateway_routes_loop_delay`|`aap_configuration_loop_delay`|no|This variable sets the loop_delay for the role.| +|`aap_configuration_async_dir`|`null`|no|Sets the directory to write the results file for async tasks. The default value is set to `null` which uses the Ansible Default of `/root/.ansible_async/`.| + +## Data Structure + +### Service Arguments + +Options for the `routes_list` variable: + +| Variable Name | Default Value | Required | Type | Description | +| `name` | N/A | yes | str | The name of the route | +| `new_name` | N/A | no | str | Setting this option will change the existing name (looked up via the name field) | +| `description` | "" | no | str | Description of the route | +| `gateway_path` | N/A | no | str | Path on the AAP gateway to listen to traffic on | +| `http_port` | N/A | no | str | ID or name referencing the [Http Port](../gateway_http_ports/README.md) | +| `service_cluster` | N/A | no | str | ID or name referencing the [Service Cluster](../gateway_service_clusters/README.md) | +| `is_service_https` | `false` | no | bool | Flag whether or not the service cluster uses https | +| `enable_gateway_auth` | N/A (`true` by API) | no | bool | If false, the AAP gateway will not insert a gateway token into the proxied request | +| `service_path` | N/A | no | str | URL path on the AAP Service cluster to route traffic to | +| `service_port` | N/A | no | int | Port on the service cluster to route traffic to | +| `tags` | "" | no | str | Comma-separated string, selects which (tagged) nodes receive traffic from this route| +| `state` | `present` | no | str | README.md#state-variable) | + +**Unique value:** + +- `name` +- `http_port` + `gateway_path` + +**Note**: `gateway_path` can't start with `/api/` prefix + +## Usage + +### Json Example + +- Check that Controller's config route exists +- Update gateway route to the port 8000 and path '/non-api/v2' +- Create or update EDA Route to gateway proxy port (http port) with id 1 and Service Cluster with id 2 (in the database) + +```json +{ + "gateway_services": [ + { + "name": "Controller Config Route", + "state": "exists" + }, + { + "name": "Gateway Non-api Route", + "http_port": "Port 8000", + "gateway_path": "/non-api/v2", + "enable_gateway_auth": false + }, + { + "name": "EDA Config Route", + "service_cluster": 2, + "http_port": 1, + "gateway_path": "/config/eda/", + "service_path": "/config/v1/", + "service_port": 9000 + } + ] +} +``` + +### Yaml Example + +- Checks that non-api routes to services exist +- If at least one doesn't exist, playbook fails. + +File name: `data/gateway_routes.yml` + +```yaml +platform_state: exists +routes_list: +- name: "Controller Config route" + gateway_path: '/config/controller/' + http_port: Port 8000 +- name: "Hub Config route" +- name: 3 +- name: 4 +``` + +## License + +[GPL-3.0](https://github.com/redhat-cop/aap_configuration#licensing) diff --git a/collections/controller_configuration/gateway_service_clusters.md b/collections/controller_configuration/gateway_service_clusters.md new file mode 100644 index 0000000..815640b --- /dev/null +++ b/collections/controller_configuration/gateway_service_clusters.md @@ -0,0 +1,115 @@ +--- +layout: default +title: gateway_service_clusters +parent: infra.controller_configuration +--- + +# Ansible Role infra.aap_configuration.service_clusters + +## Description + +An Ansible Role to configure Service Clusters on Ansible Automation gateway. + +## Variables + +|Variable Name|Default Value|Required|Description|Example| +|`platform_state`|"present"|no|The state all objects will take unless overridden by object default|'absent'| +|`aap_hostname`|""|yes|URL to the Ansible Automation Platform Server.|127.0.0.1| +|`aap_validate_certs`|`True`|no|Whether or not to validate the Ansible Automation Platform Server's SSL certificate.|| +|`aap_username`|""|no|Admin User on the Ansible Automation Platform Server. Either username / password or oauthtoken need to be specified.|| +|`aap_password`|""|no|Platform Admin User's password on the Server. This should be stored in an Ansible Vault at vars/platform-secrets.yml or elsewhere and called from a parent playbook.|| +|`aap_token`|""|no|Controller Admin User's token on the Ansible Automation Platform Server. This should be stored in an Ansible Vault at or elsewhere and called from a parent playbook. Either username / password or oauthtoken need to be specified.|| +|`aap_request_timeout`|`10`|no|Specify the timeout in seconds Ansible should use in requests to the Ansible Automation Platform host.|| +|`gateway_service_clusters`|`see below`|yes|Data structure describing your gateway_service_clusters Described below.|| + +### Secure Logging Variables + +The following Variables compliment each other. +If Both variables are not set, secure logging defaults to false. +The role defaults to False as normally the add ee_registry task does not include sensitive information. +gateway_service_clusters_secure_logging defaults to the value of aap_configuration_secure_logging if it is not explicitly called. This allows for secure logging to be toggled for the entire suite of automation hub configuration roles with a single variable, or for the user to selectively use it. + +|Variable Name|Default Value|Required|Description| +|`gateway_service_clusters_secure_logging`|`False`|no|Whether or not to include the sensitive Registry role tasks in the log. Set this value to `True` if you will be providing your sensitive values from elsewhere.| +|`aap_configuration_secure_logging`|`False`|no|This variable enables secure logging as well, but is shared across multiple roles, see above.| + +### Asynchronous Retry Variables + +The following Variables set asynchronous retries for the role. +If neither of the retries or delay or retries are set, they will default to their respective defaults. +This allows for all items to be created, then checked that the task finishes successfully. +This also speeds up the overall role. + +|Variable Name|Default Value|Required|Description| +|`aap_configuration_async_retries`|50|no|This variable sets the number of retries to attempt for the role globally.| +|`gateway_service_clusters_async_retries`|`aap_configuration_async_retries`|no|This variable sets the number of retries to attempt for the role.| +|`aap_configuration_async_delay`|1|no|This sets the delay between retries for the role globally.| +|`gateway_service_clusters_async_delay`|`aap_configuration_async_delay`|no|This sets the delay between retries for the role.| +|`aap_configuration_loop_delay`|1000|no|This variable sets the loop_delay for the role globally.| +|`gateway_service_clusters_loop_delay`|`aap_configuration_loop_delay`|no|This variable sets the loop_delay for the role.| +|`aap_configuration_async_dir`|`null`|no|Sets the directory to write the results file for async tasks. The default value is set to `null` which uses the Ansible Default of `/root/.ansible_async/`.| + +## Data Structure + +### Service Cluster Arguments + +Options for the `gateway_service_nodes` variable: + +| Variable Name | Default Value | Required | Type | Description | +| `name` | N/A | yes | str | The name of the resource | +| `new_name` | N/A | no | str | Setting this option will change the existing name (looked up via the name field) | +| `service_type` | N/A | state is 'present' | str | The type of service for this cluster. Choices : ["hub", "controller", "eda", "gateway"] | +| `state` | `present` | no | str | README.md#state-variable) | + +**Unique value:** + +- `name` +- `service_type` + +## Usage + +### Json Example + +- Check that Controller and EDA (Event Driven Automation) services are deleted (if present) (from the database): +- Check that gateway service exists (in the database) + +```json +{ + "platform_state": "absent", + "gateway_service_clusters": [ + { + "name": "Automation Controller" + }, + { + "name": "Event Driven Automation" + }, + { + "name": "AAP gateway", + "state": "exists" + } + ] +} +``` + +### Yaml Example + +- Create or update Controller Service (in the database) +- CHeck that Service with ID 3 exists +- Renames Hub service + +File name: `data/service_clusters.yml` + +```yaml +gateway_service_clusters: +- name: "Automation Controller" + service_type: controller + state: present +- name: 3 + state: exists +- name: "Automation Hub" + new_name: "Ansible Galaxy" + ``` + +## License + +[GPL-3.0](https://github.com/redhat-cop/aap_configuration#licensing) diff --git a/collections/controller_configuration/gateway_service_keys.md b/collections/controller_configuration/gateway_service_keys.md new file mode 100644 index 0000000..c4f02fc --- /dev/null +++ b/collections/controller_configuration/gateway_service_keys.md @@ -0,0 +1,116 @@ +--- +layout: default +title: gateway_service_keys +parent: infra.controller_configuration +--- + +# Ansible Role infra.aap_configuration.service_keys + +## Description + +An Ansible Role to configure Service Keys on Ansible Automation gateway. + +## Variables + +|Variable Name|Default Value|Required|Description|Example| +|`platform_state`|"present"|no|The state all objects will take unless overridden by object default|'absent'| +|`aap_hostname`|""|yes|URL to the Ansible Automation Platform Server.|127.0.0.1| +|`aap_validate_certs`|`True`|no|Whether or not to validate the Ansible Automation Platform Server's SSL certificate.|| +|`aap_username`|""|no|Admin User on the Ansible Automation Platform Server. Either username / password or oauthtoken need to be specified.|| +|`aap_password`|""|no|Platform Admin User's password on the Server. This should be stored in an Ansible Vault at vars/platform-secrets.yml or elsewhere and called from a parent playbook.|| +|`aap_token`|""|no|Controller Admin User's token on the Ansible Automation Platform Server. This should be stored in an Ansible Vault at or elsewhere and called from a parent playbook. Either username / password or oauthtoken need to be specified.|| +|`aap_request_timeout`|`10`|no|Specify the timeout in seconds Ansible should use in requests to the Ansible Automation Platform host.|| +|`gateway_service_keys`|`see below`|yes|Data structure describing your gateway_service_keys Described below.|| + +### Secure Logging Variables + +The following Variables compliment each other. +If Both variables are not set, secure logging defaults to false. +The role defaults to False as normally the add ee_registry task does not include sensitive information. +gateway_service_keys_secure_logging defaults to the value of aap_configuration_secure_logging if it is not explicitly called. This allows for secure logging to be toggled for the entire suite of automation hub configuration roles with a single variable, or for the user to selectively use it. + +|Variable Name|Default Value|Required|Description| +|`gateway_service_keys_secure_logging`|`False`|no|Whether or not to include the sensitive Registry role tasks in the log. Set this value to `True` if you will be providing your sensitive values from elsewhere.| +|`aap_configuration_secure_logging`|`False`|no|This variable enables secure logging as well, but is shared across multiple roles, see above.| + +### Asynchronous Retry Variables + +The following Variables set asynchronous retries for the role. +If neither of the retries or delay or retries are set, they will default to their respective defaults. +This allows for all items to be created, then checked that the task finishes successfully. +This also speeds up the overall role. + +|Variable Name|Default Value|Required|Description| +|`aap_configuration_async_retries`|50|no|This variable sets the number of retries to attempt for the role globally.| +|`gateway_service_keys_async_retries`|`aap_configuration_async_retries`|no|This variable sets the number of retries to attempt for the role.| +|`aap_configuration_async_delay`|1|no|This sets the delay between retries for the role globally.| +|`gateway_service_keys_async_delay`|`aap_configuration_async_delay`|no|This sets the delay between retries for the role.| +|`aap_configuration_loop_delay`|1000|no|This variable sets the loop_delay for the role globally.| +|`gateway_service_keys_loop_delay`|`aap_configuration_loop_delay`|no|This variable sets the loop_delay for the role.| +|`aap_configuration_async_dir`|`null`|no|Sets the directory to write the results file for async tasks. The default value is set to `null` which uses the Ansible Default of `/root/.ansible_async/`.| + +## Data Structure + +### Service Key Arguments + +Options for the `gateway_service_keys` variable: + +| Variable Name | Default Value | Required | Type | Description | +| `name` | N/A | yes | str | The name of the resource | +| `new_name` | N/A | no | str | Setting this option will change the existing name (looked up via the name field) | +| `is_active` | N/A (true by API) | no | bool | Flag for setting the active state of the Service Key | +| `service_cluster` | N/A | no | str | ID or name referencing the [Service Cluster](../gateway_service_clusters/README.md) | +| `algorithm` | N/A (HS256 by API) | no | str | Algorithm to use for this Service Key. Choices: ["HS256", "HS384", "HS512"] | +| `secret` | N/A | no | str | A secret to use for this Service Key. Non-editable | +| `secret_length` | N/A | no | int | The number of random bytes in the secret | +| `mark_previous_inactive` | N/A | no | bool | If true any other secret keys for this service will become inactive | +| `state` | `present` | no | str | README.md#state-variable) | + +**Unique value:** + +- `name` + +## Usage + +### Json Example + +- Check the service key exists (in the database): +- Create a service key + +```json +{ + "gateway_service_keys": [ + { + "name": "Key 1", + "state": "exists" + }, + { + "name": "Key 2", + "algorithm": "HS512", + "secret": "this-is-secret", + "service_cluster": "Automation Controller" + } + ] +} +``` + +### Yaml Example + +- Create inactive key for Controller service +- Delete key (if exists) + +File name: `data/gateway_service_keys.yml` + +```yaml +gateway_service_keys: +- name: "Controller Key 1" + is_active: false + service_cluster: controller + secret: "gateway-secret" +- name: "Some secret key" + state: absent +``` + +## License + +[GPL-3.0](https://github.com/redhat-cop/aap_configuration#licensing) diff --git a/collections/controller_configuration/gateway_service_nodes.md b/collections/controller_configuration/gateway_service_nodes.md new file mode 100644 index 0000000..0bb8982 --- /dev/null +++ b/collections/controller_configuration/gateway_service_nodes.md @@ -0,0 +1,126 @@ +--- +layout: default +title: gateway_service_nodes +parent: infra.controller_configuration +--- + +# Ansible Role infra.aap_configuration.service_nodes + +## Description + +An Ansible Role to configure Service Nodes on Ansible Automation gateway. + +## Variables + +|Variable Name|Default Value|Required|Description|Example| +|`platform_state`|"present"|no|The state all objects will take unless overridden by object default|'absent'| +|`aap_hostname`|""|yes|URL to the Ansible Automation Platform Server.|127.0.0.1| +|`aap_validate_certs`|`True`|no|Whether or not to validate the Ansible Automation Platform Server's SSL certificate.|| +|`aap_username`|""|no|Admin User on the Ansible Automation Platform Server. Either username / password or oauthtoken need to be specified.|| +|`aap_password`|""|no|Platform Admin User's password on the Server. This should be stored in an Ansible Vault at vars/platform-secrets.yml or elsewhere and called from a parent playbook.|| +|`aap_token`|""|no|Controller Admin User's token on the Ansible Automation Platform Server. This should be stored in an Ansible Vault at or elsewhere and called from a parent playbook. Either username / password or oauthtoken need to be specified.|| +|`aap_request_timeout`|`10`|no|Specify the timeout in seconds Ansible should use in requests to the Ansible Automation Platform host.|| +|`gateway_service_nodes`|`see below`|yes|Data structure describing your gateway_service_nodes Described below.|| + +### Enforcing defaults + +The following Variables compliment each other. +If Both variables are not set, enforcing default values is not done. +Enabling these variables enforce default values on options that are optional in the controller API. +This should be enabled to enforce configuration and prevent configuration drift. It is recomended to be enabled, however it is not enforced by default. + +Enabling this will enforce configurtion without specifying every option in the configuration files. + +'gateway_service_nodes_enforce_defaults' defaults to the value of 'aap_configuration_enforce_defaults' if it is not explicitly called. This allows for enforced defaults to be toggled for the entire suite of controller configuration roles with a single variable, or for the user to selectively use it. + +|Variable Name|Default Value|Required|Description| +|`gateway_service_nodes_enforce_defaults`|`False`|no|Whether or not to enforce default option values on only the applications role| +|`aap_configuration_enforce_defaults`|`False`|no|This variable enables enforced default values as well, but is shared globally.| + +### Secure Logging Variables + +The following Variables compliment each other. +If Both variables are not set, secure logging defaults to false. +The role defaults to False as normally the add ee_registry task does not include sensitive information. +gateway_service_nodes_secure_logging defaults to the value of aap_configuration_secure_logging if it is not explicitly called. This allows for secure logging to be toggled for the entire suite of automation hub configuration roles with a single variable, or for the user to selectively use it. + +|Variable Name|Default Value|Required|Description| +|`gateway_service_nodes_secure_logging`|`False`|no|Whether or not to include the sensitive Registry role tasks in the log. Set this value to `True` if you will be providing your sensitive values from elsewhere.| +|`aap_configuration_secure_logging`|`False`|no|This variable enables secure logging as well, but is shared across multiple roles, see above.| + +### Asynchronous Retry Variables + +The following Variables set asynchronous retries for the role. +If neither of the retries or delay or retries are set, they will default to their respective defaults. +This allows for all items to be created, then checked that the task finishes successfully. +This also speeds up the overall role. + +|Variable Name|Default Value|Required|Description| +|`aap_configuration_async_retries`|50|no|This variable sets the number of retries to attempt for the role globally.| +|`gateway_service_nodes_async_retries`|`aap_configuration_async_retries`|no|This variable sets the number of retries to attempt for the role.| +|`aap_configuration_async_delay`|1|no|This sets the delay between retries for the role globally.| +|`gateway_service_nodes_async_delay`|`aap_configuration_async_delay`|no|This sets the delay between retries for the role.| +|`aap_configuration_loop_delay`|1000|no|This variable sets the loop_delay for the role globally.| +|`gateway_service_nodes_loop_delay`|`aap_configuration_loop_delay`|no|This variable sets the loop_delay for the role.| +|`aap_configuration_async_dir`|`null`|no|Sets the directory to write the results file for async tasks. The default value is set to `null` which uses the Ansible Default of `/root/.ansible_async/`.| + +## Data Structure + +### Service Node Arguments + +Options for the `service_nodes_list` variable: + +| Variable Name | Default Value | Required | Type | Description | +| `name` | N/A | yes | str | The name of the resource | +| `new_name` | N/A | no | str | Setting this option will change the existing name (looked up via the name field) | +| `address` | N/A | no | str | Network address for this service | +| `service_cluster` | N/A | no | str | ID or name referencing the [Service Cluster](../gateway_service_clusters/README.md) | +| `tags` | N/A | no | str | Comma separated list of tags to assign to the node, for filtering route traffic | +| `state` | `present` | no | str | README.md#state-variable) | + +**Unique value:** + +- `name` +- `address` + `service_cluster` + +## Usage + +### Json Example + +- Check the node on 10.0.0.1 for EDA service exists (in the database): +- Check the node with ID 1 exists (in the database): + +```json +{ + "gateway_service_nodes": [ + { + "name": "EDA - 10.0.0.1", + "state": "exists" + }, + { + "name": 1, + "state": "exists" + } + ] +} +``` + +### Yaml Example + +- Create node (if not exists) for Controller service (in the database) +- Delete node (if exists) for Automation Hub Service (from the database) + +File name: `data/service_nodes.yml` + +```yaml +gateway_service_nodes: +- name: "Controller Node 1" + address: 10.0.0.1 + service_cluster: controller +- name: "Hub on 10.0.1.1" + state: absent +``` + +## License + +[GPL-3.0](https://github.com/redhat-cop/aap_configuration#licensing) diff --git a/collections/controller_configuration/gateway_services.md b/collections/controller_configuration/gateway_services.md new file mode 100644 index 0000000..c34c389 --- /dev/null +++ b/collections/controller_configuration/gateway_services.md @@ -0,0 +1,136 @@ +--- +layout: default +title: gateway_services +parent: infra.controller_configuration +--- + +# Ansible Role infra.aap_configuration.services + +## Description + +An Ansible Role to configure gateway API routes (called Service) on Ansible Automation gateway. +They define http port and path (starting with prefix /api/) used in gateway and +http port and path in the destination service (gateway, controller, hub, eda). + +## Variables + +|Variable Name|Default Value|Required|Description|Example| +|`platform_state`|"present"|no|The state all objects will take unless overridden by object default|'absent'| +|`aap_hostname`|""|yes|URL to the Ansible Automation Platform Server.|127.0.0.1| +|`aap_validate_certs`|`True`|no|Whether or not to validate the Ansible Automation Platform Server's SSL certificate.|| +|`aap_username`|""|no|Admin User on the Ansible Automation Platform Server. Either username / password or oauthtoken need to be specified.|| +|`aap_password`|""|no|Platform Admin User's password on the Server. This should be stored in an Ansible Vault at vars/platform-secrets.yml or elsewhere and called from a parent playbook.|| +|`aap_token`|""|no|Controller Admin User's token on the Ansible Automation Platform Server. This should be stored in an Ansible Vault at or elsewhere and called from a parent playbook. Either username / password or oauthtoken need to be specified.|| +|`aap_request_timeout`|`10`|no|Specify the timeout in seconds Ansible should use in requests to the Ansible Automation Platform host.|| +|`gateway_services`|`see below`|yes|Data structure describing your gateway_services Described below.|| + +### Secure Logging Variables + +The following Variables compliment each other. +If Both variables are not set, secure logging defaults to false. +The role defaults to False as normally the add ee_registry task does not include sensitive information. +gateway_services_secure_logging defaults to the value of aap_configuration_secure_logging if it is not explicitly called. This allows for secure logging to be toggled for the entire suite of automation hub configuration roles with a single variable, or for the user to selectively use it. + +|Variable Name|Default Value|Required|Description| +|`gateway_services_secure_logging`|`False`|no|Whether or not to include the sensitive Registry role tasks in the log. Set this value to `True` if you will be providing your sensitive values from elsewhere.| +|`aap_configuration_secure_logging`|`False`|no|This variable enables secure logging as well, but is shared across multiple roles, see above.| + +### Asynchronous Retry Variables + +The following Variables set asynchronous retries for the role. +If neither of the retries or delay or retries are set, they will default to their respective defaults. +This allows for all items to be created, then checked that the task finishes successfully. +This also speeds up the overall role. + +|Variable Name|Default Value|Required|Description| +|`aap_configuration_async_retries`|50|no|This variable sets the number of retries to attempt for the role globally.| +|`gateway_services_async_retries`|`aap_configuration_async_retries`|no|This variable sets the number of retries to attempt for the role.| +|`aap_configuration_async_delay`|1|no|This sets the delay between retries for the role globally.| +|`gateway_services_async_delay`|`aap_configuration_async_delay`|no|This sets the delay between retries for the role.| +|`aap_configuration_loop_delay`|1000|no|This variable sets the loop_delay for the role globally.| +|`gateway_services_loop_delay`|`aap_configuration_loop_delay`|no|This variable sets the loop_delay for the role.| +|`aap_configuration_async_dir`|`null`|no|Sets the directory to write the results file for async tasks. The default value is set to `null` which uses the Ansible Default of `/root/.ansible_async/`.| + +## Data Structure + +### Service Arguments + +Options for the `gateway_services` variable: + +| Variable Name | Default Value | Required | Type | Description | +| `name` | N/A | yes | str | The name of the api | +| `new_name` | N/A | no | str | Setting this option will change the existing name (looked up via the name field) | +| `description` | "" | no | str | Description of the service | +| `api_slug` | "" | no | str | URL slug for the gateway API path for the Controller, Hub and EDA services (gateway API route requires value "gateway", but the slug is not used) | +| `http_port` | N/A | no | str | ID or name referencing the [Http Port](../gateway_http_ports/README.md) | +| `service_cluster` | N/A | no | str | ID or name referencing the [Service Cluster](../gateway_service_clusters/README.md) | +| `is_service_https` | `false` | no | bool | Flag whether or not the service cluster uses https | +| `enable_gateway_auth` | N/A (`true` by API) | no | bool | If false, the AAP gateway will not insert a gateway token into the proxied request | +| `service_path` | "" | no | str | URL path on the AAP Service cluster to route traffic to | +| `service_port` | N/A | no | int | Port on the service cluster to route traffic to | +| `order` | "" (`50` by API) | no | int | The order to apply the routes in lower numbers are first. Items with the same value have no guaranteed order | +| `tags` | "" | no | str | Comma-separated string, selects which (tagged) nodes receive traffic from this route | +| `state` | `present` | no | str | README.md#state-variable) | + +**Unique value:** + +- `name` +- `http_port` + `service_cluster` + +**Note**: field `gateway_path` is inferred from the `api_slug`, always starts with `/api/` and is read only. + +## Usage + +### Json Example + +- Check that Controller API Route exists +- Create or update gateway API Route on proxy port (http port) with id 1 and path '/' proxying gateway on path ' + /api/v1/' and port 9000 +- Create or update EDA API Route on proxy port (http port) 8000 and path '/api/eda/' proxying Event Driven + Automation on path '/api/v2/' and port 9000. Lookup for existing name "EDA API", but create/update with different name + +```json +{ + "gateway_services": [ + { + "name": "Controller API", + "state": "exists" + }, + { + "name": "gateway API", + "http_port": 1, + "service_cluster": "gateway", + "service_path": "/api/v1/", + "service_port": 9000 + }, + { + "name": "EDA API", + "new_name": "Event Driven Automation API", + "http_port": "Port 8000", + "api_slug": "eda", + "service_cluster": "eda", + "service_path": "/api/v2/", + "service_port": 9000 + } + ] +} +``` + +### Yaml Example + +- Remove all gateway Services (resp. their proxy configurations) + +File name: `data/services.yml` + +```yaml +platform_state: absent +gateway_service_clusters: +- name: Controller API +- name: Hub API +- name: EDA API +- name: Gateway API +``` + +## License + +[GPL-3.0](https://github.com/redhat-cop/aap_configuration#licensing) diff --git a/collections/controller_configuration/gateway_settings.md b/collections/controller_configuration/gateway_settings.md new file mode 100644 index 0000000..b7dea61 --- /dev/null +++ b/collections/controller_configuration/gateway_settings.md @@ -0,0 +1,84 @@ +--- +layout: default +title: gateway_settings +parent: infra.controller_configuration +--- + +# Ansible Role infra.aap_configuration.settings + +An Ansible role to alter Settings on Ansible Automation Gateway. + +## Variables + +|Variable Name|Default Value|Required|Description|Example| +|`platform_state`|"present"|no|The state all objects will take unless overridden by object default|'absent'| +|`aap_hostname`|""|yes|URL to the Ansible Automation Platform Server.|127.0.0.1| +|`aap_validate_certs`|`True`|no|Whether or not to validate the Ansible Automation Platform Server's SSL certificate.|| +|`aap_username`|""|no|Admin User on the Ansible Automation Platform Server. Either username / password or oauthtoken need to be specified.|| +|`aap_password`|""|no|Platform Admin User's password on the Server. This should be stored in an Ansible Vault at vars/platform-secrets.yml or elsewhere and called from a parent playbook.|| +|`aap_token`|""|no|Controller Admin User's token on the Ansible Automation Platform Server. This should be stored in an Ansible Vault at or elsewhere and called from a parent playbook. Either username / password or oauthtoken need to be specified.|| +|`aap_request_timeout`|`10`|no|Specify the timeout in seconds Ansible should use in requests to the Ansible Automation Platform host.|| +|`gateway_settings`|`see below`|yes|Data structure describing your gateway_services Described below.|| + +### Secure Logging Variables + +The following Variables compliment each other. +If Both variables are not set, secure logging defaults to false. +The role defaults to False as normally the add ee_registry task does not include sensitive information. +gateway_services_secure_logging defaults to the value of aap_configuration_secure_logging if it is not explicitly called. This allows for secure logging to be toggled for the entire suite of automation hub configuration roles with a single variable, or for the user to selectively use it. + +|Variable Name|Default Value|Required|Description| +|`gateway_services_secure_logging`|`False`|no|Whether or not to include the sensitive Registry role tasks in the log. Set this value to `True` if you will be providing your sensitive values from elsewhere.| +|`aap_configuration_secure_logging`|`False`|no|This variable enables secure logging as well, but is shared across multiple roles, see above.| + +## Data Structure + +### Settings arguments + +Provide settings as a single dict under `settings_list`. + +## Usage + +### Json Example + +```json +{ + "gateway_settings": { + "gateway_token_name": "X-DAB-JW-TOKEN", + "gateway_access_token_expiration": 600, + "gateway_basic_auth_enabled": true, + "gateway_proxy_url": "https://localhost:9080", + "gateway_proxy_url_ignore_cert": false, + "password_min_length": 0, + "password_min_digits": 0, + "password_min_upper": 0, + "password_min_special": 0, + "allow_admins_to_set_insecure": false + } +} + +``` + +### Yaml Example + +File name: `data/gateway_settings.yml` + +```yaml +gateway_settings: + gateway_token_name: X-DAB-JW-TOKEN + gateway_access_token_expiration: 600 + gateway_basic_auth_enabled: true + gateway_proxy_url: https://localhost:9080 + gateway_proxy_url_ignore_cert: false + password_min_length: 0 + password_min_digits: 0 + password_min_upper: 0 + password_min_special: 0 + allow_admins_to_set_insecure: false + + +``` + +## License + +[GPL-3.0](https://github.com/redhat-cop/aap_configuration#licensing) diff --git a/collections/controller_configuration/gateway_teams.md b/collections/controller_configuration/gateway_teams.md new file mode 100644 index 0000000..d6f8137 --- /dev/null +++ b/collections/controller_configuration/gateway_teams.md @@ -0,0 +1,116 @@ +--- +layout: default +title: gateway_teams +parent: infra.controller_configuration +--- + +# Ansible Role infra.aap_configuration.teams + +## Description + +An Ansible Role to add Teams on Ansible Automation gateway. + +## Variables + +|Variable Name|Default Value|Required|Description|Example| +|`platform_state`|"present"|no|The state all objects will take unless overridden by object default|'absent'| +|`aap_hostname`|""|yes|URL to the Ansible Automation Platform Server.|127.0.0.1| +|`aap_validate_certs`|`True`|no|Whether or not to validate the Ansible Automation Platform Server's SSL certificate.|| +|`aap_username`|""|no|Admin User on the Ansible Automation Platform Server. Either username / password or oauthtoken need to be specified.|| +|`aap_password`|""|no|Platform Admin User's password on the Server. This should be stored in an Ansible Vault at vars/platform-secrets.yml or elsewhere and called from a parent playbook.|| +|`aap_token`|""|no|Controller Admin User's token on the Ansible Automation Platform Server. This should be stored in an Ansible Vault at or elsewhere and called from a parent playbook. Either username / password or oauthtoken need to be specified.|| +|`aap_request_timeout`|`10`|no|Specify the timeout in seconds Ansible should use in requests to the Ansible Automation Platform host.|| +|`aap_teams`|`see below`|yes|Data structure describing your teams Described below.|| + +### Secure Logging Variables + +The following Variables compliment each other. +If Both variables are not set, secure logging defaults to false. +The role defaults to False as normally the add ee_registry task does not include sensitive information. +gateway_teams_secure_logging defaults to the value of aap_configuration_secure_logging if it is not explicitly called. This allows for secure logging to be toggled for the entire suite of automation hub configuration roles with a single variable, or for the user to selectively use it. + +|Variable Name|Default Value|Required|Description| +|`gateway_teams_secure_logging`|`False`|no|Whether or not to include the sensitive Registry role tasks in the log. Set this value to `True` if you will be providing your sensitive values from elsewhere.| +|`aap_configuration_secure_logging`|`False`|no|This variable enables secure logging as well, but is shared across multiple roles, see above.| + +### Asynchronous Retry Variables + +The following Variables set asynchronous retries for the role. +If neither of the retries or delay or retries are set, they will default to their respective defaults. +This allows for all items to be created, then checked that the task finishes successfully. +This also speeds up the overall role. + +|Variable Name|Default Value|Required|Description| +|`aap_configuration_async_retries`|50|no|This variable sets the number of retries to attempt for the role globally.| +|`gateway_teams_async_retries`|`aap_configuration_async_retries`|no|This variable sets the number of retries to attempt for the role.| +|`aap_configuration_async_delay`|1|no|This sets the delay between retries for the role globally.| +|`gateway_teams_async_delay`|`aap_configuration_async_delay`|no|This sets the delay between retries for the role.| +|`aap_configuration_loop_delay`|1000|no|This variable sets the loop_delay for the role globally.| +|`gateway_teams_loop_delay`|`aap_configuration_loop_delay`|no|This variable sets the loop_delay for the role.| +|`aap_configuration_async_dir`|`null`|no|Sets the directory to write the results file for async tasks. The default value is set to `null` which uses the Ansible Default of `/root/.ansible_async/`.| + +## Data Structure + +### Team Arguments + +Options for the `teams` variable: + +| Variable Name | Default Value | Required | Type | Description | +| `name` | N/A | yes | str | The name of the resource | +| `new_name` | N/A | no | str | Setting this option will change the existing name (looked up via the name field) | +| `description` | N/A | no | str | Description of the organization | +| `organization` | N/A | yes | str | The name or ID referencing the [Organization](../gateway_organizations/README.md) | +| `new_organization` | N/A | no | str | The name or ID referencing newly associated organization | +| `state` | `present` | no | str | Desired state of the resource. | + +### Unique value + +- [`name`, `organization`] + +## Usage + +### Json Example + +- Create 2 Teams + +```json +{ + "teams": [ + { + "name": "Team 1", + "description": "Best team", + "organization": "IT Department" + }, + { + "name": "Team 2", + "organization": "1" + } + ] +} +``` + +### Yaml Example + +- Check that Happy Team in Productive Organization exists +- Check that Managers Team doesn't exist, or delete it +- Rename Team X and Reassign it to another organization + +File name: `data/gateway_teams.yml` + +```yaml +teams: +- name: "Happy Team" + organization: "Productive Organization" + state: exists +- name: "Managers" + organization: "Org X" + state: absent +- name: "Team X" + new_name: "Secret Team" + organization: "Org X" + new_organization: "Secret Organization" +``` + +## License + +[GPL-3.0](https://github.com/redhat-cop/aap_configuration#licensing) diff --git a/collections/controller_configuration/gateway_users.md b/collections/controller_configuration/gateway_users.md new file mode 100644 index 0000000..ae568a1 --- /dev/null +++ b/collections/controller_configuration/gateway_users.md @@ -0,0 +1,114 @@ +--- +layout: default +title: gateway_users +parent: infra.controller_configuration +--- + +# Ansible Role infra.aap_configuration.users + +## Description + +An Ansible Role to configure users on Ansible Automation gateway. + +## Variables + +|Variable Name|Default Value|Required|Description|Example| +|`platform_state`|"present"|no|The state all objects will take unless overridden by object default|'absent'| +|`aap_hostname`|""|yes|URL to the Ansible Automation Platform Server.|127.0.0.1| +|`aap_validate_certs`|`True`|no|Whether or not to validate the Ansible Automation Platform Server's SSL certificate.|| +|`aap_username`|""|no|Admin User on the Ansible Automation Platform Server. Either username / password or oauthtoken need to be specified.|| +|`aap_password`|""|no|Platform Admin User's password on the Server. This should be stored in an Ansible Vault at vars/platform-secrets.yml or elsewhere and called from a parent playbook.|| +|`aap_token`|""|no|Controller Admin User's token on the Ansible Automation Platform Server. This should be stored in an Ansible Vault at or elsewhere and called from a parent playbook. Either username / password or oauthtoken need to be specified.|| +|`aap_request_timeout`|`10`|no|Specify the timeout in seconds Ansible should use in requests to the Ansible Automation Platform host.|| +|`aap_user_accounts`|`see below`|yes|Data structure describing your users Described below.|| + +### Secure Logging Variables + +The following Variables compliment each other. +If Both variables are not set, secure logging defaults to false. +The role defaults to False as normally the add ee_registry task does not include sensitive information. +gateway_users_secure_logging defaults to the value of aap_configuration_secure_logging if it is not explicitly called. This allows for secure logging to be toggled for the entire suite of automation hub configuration roles with a single variable, or for the user to selectively use it. + +|Variable Name|Default Value|Required|Description| +|`gateway_users_secure_logging`|`False`|no|Whether or not to include the sensitive Registry role tasks in the log. Set this value to `True` if you will be providing your sensitive values from elsewhere.| +|`aap_configuration_secure_logging`|`False`|no|This variable enables secure logging as well, but is shared across multiple roles, see above.| + +### Asynchronous Retry Variables + +The following Variables set asynchronous retries for the role. +If neither of the retries or delay or retries are set, they will default to their respective defaults. +This allows for all items to be created, then checked that the task finishes successfully. +This also speeds up the overall role. + +|Variable Name|Default Value|Required|Description| +|`aap_configuration_async_retries`|50|no|This variable sets the number of retries to attempt for the role globally.| +|`gateway_users_async_retries`|`aap_configuration_async_retries`|no|This variable sets the number of retries to attempt for the role.| +|`aap_configuration_async_delay`|1|no|This sets the delay between retries for the role globally.| +|`gateway_users_async_delay`|`aap_configuration_async_delay`|no|This sets the delay between retries for the role.| +|`aap_configuration_loop_delay`|1000|no|This variable sets the loop_delay for the role globally.| +|`gateway_users_loop_delay`|`aap_configuration_loop_delay`|no|This variable sets the loop_delay for the role.| +|`aap_configuration_async_dir`|`null`|no|Sets the directory to write the results file for async tasks. The default value is set to `null` which uses the Ansible Default of `/root/.ansible_async/`.| + +## Data Structure + +### User Arguments + +Options for the `aap_user_accounts` variable: + +| Variable Name | Default Value | Required | Type | Description | +| `username` | N/A | yes | str | The username of the user | +| `password` | "{{ users_default_password }}" | no | str | The password of the user | +| `email` | N/A | yes | str | The email of the user | +| `first_name` | "" | no | str | The first name of the user | +| `last_name` | "" | no | str | The last name of the user | +| `is_superuser` | `false` | no | bool | Whether the user is a superuser | +| `authenticators` | N/A | no | list | List of authenticators this user is associated with | +| `authenticator_uid` | N/A | no | bool | UID coming from the authenticators the user is associated with | +| `state` | `present` | no | str | Desired state of the resource. | +| `update_secrets` | 'true' | no | bool | True will always change password if user specifies password, even if API gives $encrypted$ for password. False will only set the password if other values change too. | + +**Unique value:** + +- `username` + +## Usage + +### Json Example + +- Creates (or updates) 2 users, one with default password "changeme". + +```json +{ + "users_default_password": "changeme", + "aap_user_accounts": [ + { + "username": "jsmith", + "is_superuser": false, + "password": "p4ssword", + "email": "jsmith@example.com" + }, + { + "username": "jdoe", + "email": "jdoe@example.com" + } + ] +} +``` + +#### Yaml Example + +- Check that users exist + +File name: `data/gateway_users.yml` + +```yaml +platform_state: exists +aap_user_accounts: +- username: jsmith +- username: jdoe +- username: admin +``` + +## License + +[GPL-3.0](https://github.com/redhat-cop/aap_configuration#licensing) diff --git a/collections/controller_configuration/global_vars.md b/collections/controller_configuration/global_vars.md new file mode 100644 index 0000000..bcaa761 --- /dev/null +++ b/collections/controller_configuration/global_vars.md @@ -0,0 +1,49 @@ +--- +layout: default +title: global_vars +parent: infra.controller_configuration +--- + +# controller_configuration.global_vars + +## Description + +An ansible role to define global variables that will be available to all of the +roles in the collection, if they are configured as follows: + +```console +# tail -4 meta/main.yml + +dependencies: +# List your role dependencies here, one per line. Be sure to remove the '[]' above, +# if you add dependencies to this list. + - global_vars +``` + +## Provided Variables + +This is currently providing the following variables: + +| Variable Name | Default Value | Required | Description | +| `operation_translate` | [See the default value below](#operation_translate-default-value) | Yes | Provides translation from object states to human interpretation | + +### operation_translate Default value + +```yaml +operation_translate: + present: + verb: "Create/Update" + action: "creation" + absent: + verb: "Remove" + action: "deletion" +... +``` + +## License + +[GPL-3.0](https://github.com/redhat-cop/aap_configuration#licensing) + +## Author + +[Ivan Aragonés](https://github.com/ivarmu) diff --git a/collections/controller_configuration/hub_collection.md b/collections/controller_configuration/hub_collection.md new file mode 100644 index 0000000..b909c68 --- /dev/null +++ b/collections/controller_configuration/hub_collection.md @@ -0,0 +1,120 @@ +--- +layout: default +title: hub_collection +parent: infra.controller_configuration +--- + +# galaxy.galaxy.collection + +## Description + +An Ansible Role to update, or destroy Automation Hub Collections. + +## Variables + +|Variable Name|Default Value|Required|Description|Example| +|`aap_hostname`|""|yes|URL to the Ansible Automation Platform Server.|127.0.0.1| +|`aap_username`|""|no|Admin User on the Ansible Automation Platform Server. Either username / password or oauthtoken need to be specified.|| +|`aap_password`|""|no|Platform Admin User's password on the Server. This should be stored in an Ansible Vault at vars/platform-secrets.yml or elsewhere and called from a parent playbook.|| +|`aap_validate_certs`|`True`|no|Whether or not to validate the Ansible Automation Platform Server's SSL certificate.|| +|`aap_request_timeout`|`10`|no|Specify the timeout Ansible should use in requests to the Galaxy or Automation Hub host.|| +|`ah_path_prefix`|""|no|API path used to access the api. Either galaxy, automation-hub, or custom|| +|`aap_configuration_async_dir`|`null`|no|Sets the directory to write the results file for async tasks. The default value is set to `null` which uses the Ansible Default of `/root/.ansible_async/`.|| +|`ah_collections`|`see below`|yes|Data structure describing your collections, described below.|| + +These are the sub options for the vars `ah_collections` which are dictionaries with the options you want. See examples for details. + +|Variable Name|Default Value|Required|Description|Example| +|`namespace`|""|yes|Namespace name. Must be lower case containing only alphanumeric characters and underscores.|"awx"| +|`name`|""|yes|Collection name. Must be lower case containing only alphanumeric characters and underscores.|| +|`version`|""|no|Collection Version. Must be lower case containing only alphanumeric characters and underscores. If not provided and 'auto_approve' true, will be derived from the path.|| +|`path`|""|no|Collection artifact file path.|| +|`wait`|"true"|no|Waits for the collection to be uploaded|| +|`auto_approve`|"true"|no|Approves a collection and requires version to be set.|| +|`timeout`|"true"||Maximum time to wait for the collection approval|| +|`interval`|"true"|10|Interval at which approval is checked|| +|`overwrite_existing`|"false"|no|Overwrites an existing collection and requires version to be set.|| +|`state`|"present"|no|Desired state of the resource|| + +The `aap_configuration_async_dir` variable sets the directory to write the results file for async tasks. +The default value is set to `null` which uses the Ansible Default of `/root/.ansible_async/`. + +### Asynchronous Retry Variables + +The following Variables set asynchronous retries for the role. +If neither of the retries or delay or retries are set, they will default to their respective defaults. +This allows for all items to be created, then checked that the task finishes successfully. +This also speeds up the overall role. + +|Variable Name|Default Value|Required|Description| +|`aap_configuration_async_timeout`|1000|no|This variable sets the async timeout for the role globally.| +|`ah_configuration_collection_async_timeout`|`aap_configuration_async_timeout`|no|This variable sets the async timeout for the role.| +|`aap_configuration_async_retries`|50|no|This variable sets the number of retries to attempt for the role globally.| +|`ah_configuration_collection_async_retries`|`aap_configuration_async_retries`|no|This variable sets the number of retries to attempt for the role.| +|`aap_configuration_loop_delay`|1000|no|This variable sets the loop_delay for the role globally.| +|`ah_configuration_collection_loop_delay`|`aap_configuration_loop_delay`|no|This variable sets the loop_delay for the role.| +|`aap_configuration_async_delay`|1|no|This sets the delay between retries for the role globally.| +|`ah_configuration_collection_async_delay`|`aap_configuration_async_delay`|no|This sets the delay between retries for the role.| + +### Secure Logging Variables + +The following Variables compliment each other. +If Both variables are not set, secure logging defaults to false. +The role defaults to False as normally the add repository task does not include sensitive information. +ah_configuration_repository_secure_logging defaults to the value of aap_configuration_secure_logging if it is not explicitly called. This allows for secure logging to be toggled for the entire suite of automation hub configuration roles with a single variable, or for the user to selectively use it. + +|Variable Name|Default Value|Required|Description| +|`ah_configuration_collection_secure_logging`|`False`|no|Whether or not to include the sensitive collection role tasks in the log. Set this value to `True` if you will be providing your sensitive values from elsewhere.| +|`aap_configuration_secure_logging`|`False`|no|This variable enables secure logging as well, but is shared across multiple roles, see above.| + +## Data Structure + +### Standard Project Data Structure + +#### Yaml Example + +```yaml +ah_collections: + - namespace: 'awx' + name: 'awx' + path: /var/tmp/collections/awx_awx-15.0.0.tar.gz + state: present + + - namespace: test_collection + name: test + version: 4.1.2 + state: absent +``` + +## Playbook Examples + +### Standard Role Usage + +```yaml +- name: Add collection + hosts: localhost + connection: local + gather_facts: false + vars: + aap_validate_certs: false + # Define following vars here, or in ah_configs/ah_auth.yml + # ah_host: ansible-ah-web-svc-test-project.example.com + # ah_token: changeme + pre_tasks: + - name: Include vars from ah_configs directory + ansible.builtin.include_vars: + dir: ./vars + extensions: ["yml"] + tags: + - always + roles: + - ../../collection +``` + +## License + +[GPLv3+](https://github.com/ansible/galaxy_collection#licensing) + +## Author + +[Inderpal Tiwana](https://github.com/inderpaltiwana/) diff --git a/collections/controller_configuration/hub_collection_remote.md b/collections/controller_configuration/hub_collection_remote.md new file mode 100644 index 0000000..6092e29 --- /dev/null +++ b/collections/controller_configuration/hub_collection_remote.md @@ -0,0 +1,127 @@ +--- +layout: default +title: hub_collection_remote +parent: infra.controller_configuration +--- + +# collection_remote + +## Description + +An Ansible Role to create a Collection Remote Repository. + +## Variables + +|Variable Name|Default Value|Required|Description|Example| +|`aap_hostname`|""|yes|URL to the Ansible Automation Platform Server.|127.0.0.1| +|`aap_username`|""|no|Admin User on the Ansible Automation Platform Server. Either username / password or oauthtoken need to be specified.|| +|`aap_password`|""|no|Platform Admin User's password on the Server. This should be stored in an Ansible Vault at vars/platform-secrets.yml or elsewhere and called from a parent playbook.|| +|`aap_validate_certs`|`True`|no|Whether or not to validate the Ansible Automation Platform Server's SSL certificate.|| +|`aap_request_timeout`|`10`|no|Specify the timeout Ansible should use in requests to the Galaxy or Automation Hub host.|| +|`ah_path_prefix`|""|no|API path used to access the api. Either galaxy, automation-hub, or custom|| +|`aap_configuration_async_dir`|`null`|no|Sets the directory to write the results file for async tasks. The default value is set to `null` which uses the Ansible Default of `/root/.ansible_async/`.|| +|`ah_collection_remotes`|`see below`|yes|Data structure describing your collection remote repository, described below.|| + +The `aap_configuration_async_dir` variable sets the directory to write the results file for async tasks. +The default value is set to `null` which uses the Ansible Default of `/root/.ansible_async/`. + +### Secure Logging Variables + +The following Variables compliment each other. +If Both variables are not set, secure logging defaults to false. +The role defaults to False as normally the add repository task does not include sensitive information. +ah_configuration_repository_secure_logging defaults to the value of aap_configuration_secure_logging if it is not explicitly called. This allows for secure logging to be toggled for the entire suite of automation hub configuration roles with a single variable, or for the user to selectively use it. + +|Variable Name|Default Value|Required|Description| +|`ah_configuration_collection_remote_secure_logging`|`False`|no|Whether or not to include the sensitive Namespace role tasks in the log. Set this value to `True` if you will be providing your sensitive values from elsewhere.| +|`aap_configuration_secure_logging`|`False`|no|This variable enables secure logging as well, but is shared across multiple roles, see above.| + +### Asynchronous Retry Variables + +The following Variables set asynchronous retries for the role. +If neither of the retries or delay or retries are set, they will default to their respective defaults. +This allows for all items to be created, then checked that the task finishes successfully. +This also speeds up the overall role. + +|Variable Name|Default Value|Required|Description| +|`aap_configuration_async_timeout`|1000|no|This variable sets the async timeout for the role globally.| +|`ah_configuration_collection_remote_async_timeout`|`aap_configuration_async_timeout`|no|This variable sets the async timeout for the role.| +|`aap_configuration_async_retries`|50|no|This variable sets the number of retries to attempt for the role globally.| +|`ah_configuration_collection_remote_async_retries`|`aap_configuration_async_retries`|no|This variable sets the number of retries to attempt for the role.| +|`aap_configuration_loop_delay`|1000|no|This variable sets the loop_delay for the role globally.| +|`ah_configuration_collection_remote_loop_delay`|`aap_configuration_loop_delay`|no|This variable sets the loop_delay for the role.| +|`aap_configuration_async_delay`|1|no|This sets the delay between retries for the role globally.| +|`ah_configuration_collection_remote_async_delay`|`aap_configuration_async_delay`|no|This sets the delay between retries for the role.| + +## Data Structure + +### Collection Remote Variables + +|Variable Name|Default Value|Required|Description|Example| +|`name`|``|yes| Repository name. Probably one of community, validated, or rh-certified|| +|`url`|`https://cloud.redhat.com/api/automation-hub/`|no|(`ah_repository_certified`)Remote URL for the repository.|`https://console.redhat.com/api/automation-hub/content/`| +|`url`|`https://galaxy.ansible.com/api/`|no|(`ah_repository_community`)Remote URL for the repository.|| +|`auth_url`|`https://sso.redhat.com/auth/realms/redhat-external/protocol/openid-connect/token`|no|(`ah_repository_certified`)Remote URL for the repository authentication if separate.|| +|`token`|``|no|Token to authenticate to the remote repository.|| +|`policy`|`immediate`|no|The policy to use when downloading content. Can be one of `immediate`, `When syncing, download all metadata and content now.`.|| +|`requirements`|``|no|Requirements, a list of collections in [requirements file format](https://docs.ansible.com/ansible/latest/collections_guide/collections_installing.html#install-multiple-collections-with-a-requirements-file) to limit thedownload from remote. This will only download provided collections. This is only the list under collections. See examples for usage.|| +|`requirements_file`|``|no|A yaml requirements file to download from remote. In requirements file format. Exclusive with `requirements` || +|`username`|``|no|Username to authenticate to the remote repository.|| +|`password`|``|no|Password to authenticate to the remote repository.|| +|`tls_validation`|`True`|no|Whether to use TLS validation against the remote repository|True| +|`client_key`|``|no|A PEM encoded private key file used for authentication|| +|`client_cert`|``|no|A PEM encoded client certificate used for authentication|| +|`ca_cert`|``|no|A PEM encoded CA certificate used for authentication|| +|`client_key_path`|``|no|Path to a PEM encoded private key file used for authentication|| +|`client_cert_path`|``|no|Path to a PEM encoded client certificate used for authentication|| +|`ca_cert_path`|``|no|Path to a PEM encoded CA certificate used for authentication|| +|`download_concurrency`|`10`|no| Number of concurrent collections to download.|| +|`max_retries`|`0`|no|Retries to use when running sync. Default is 0 which does not limit.|| +|`rate_limit`|`8`|no|Limits total download rate in requests per second.|| +|`signed_only`|`False`|no|Only download signed collections|False| +|`sync_dependencies`|`True`|no|Whether to download dependencies when syncing collections.|False| +|`proxy_url`|``|no|The URL for the proxy. Defaults to global `proxy_url` variable.|| +|`proxy_username`|``|no|The username for the proxy authentication. Defaults to global `proxy_username` variable.|| +|`proxy_password`|``|no|The password for the proxy authentication. Defaults to global `proxy_password` variable.|| +|`state`|`present`|no|Desired state of the collection_remote. Either `present` or `absent`.|| + +### Standard Project Data Structure + +#### Yaml Example + +```yaml +ah_collection_remotes: + - name: community-infra + url: https://beta-galaxy.ansible.com/ + requirements: + - name: infra.ee_utilities + - name: infra.aap_configuration +``` + +## Playbook Examples + +### Standard Role Usage + +```yaml +- name: Add repository to Automation Hub + hosts: localhost + connection: local + gather_facts: false + vars: + aap_validate_certs: false + # Define following vars here, or in ah_configs/ah_auth.yml + # ah_host: ansible-ah-web-svc-test-project.example.com + pre_tasks: + - name: Include vars from ah_configs directory + ansible.builtin.include_vars: + dir: ./vars + extensions: ["yml"] + tags: + - always + roles: + - ../../collection_remote +``` + +## License + +[GPLv3+](https://github.com/ansible/galaxy_collection#licensing) diff --git a/collections/controller_configuration/hub_collection_repository.md b/collections/controller_configuration/hub_collection_repository.md new file mode 100644 index 0000000..56e4928 --- /dev/null +++ b/collections/controller_configuration/hub_collection_repository.md @@ -0,0 +1,133 @@ +--- +layout: default +title: hub_collection_repository +parent: infra.controller_configuration +--- + +# collection_repository + +## Description + +An Ansible Role to create a Collection Repository. + +## Variables + +|Variable Name|Default Value|Required|Description|Example| +|`aap_hostname`|""|yes|URL to the Ansible Automation Platform Server.|127.0.0.1| +|`aap_username`|""|no|Admin User on the Ansible Automation Platform Server. Either username / password or oauthtoken need to be specified.|| +|`aap_password`|""|no|Platform Admin User's password on the Server. This should be stored in an Ansible Vault at vars/platform-secrets.yml or elsewhere and called from a parent playbook.|| +|`aap_validate_certs`|`True`|no|Whether or not to validate the Ansible Automation Platform Server's SSL certificate.|| +|`aap_request_timeout`|`10`|no|Specify the timeout Ansible should use in requests to the Galaxy or Automation Hub host.|| +|`ah_path_prefix`|""|no|API path used to access the api. Either galaxy, automation-hub, or custom|| +|`aap_configuration_async_dir`|`null`|no|Sets the directory to write the results file for async tasks. The default value is set to `null` which uses the Ansible Default of `/root/.ansible_async/`.|| +|`ah_collection_repositories`|`see below`|yes|Data structure describing your collection remote repository, described below.|| + +The `aap_configuration_async_dir` variable sets the directory to write the results file for async tasks. +The default value is set to `null` which uses the Ansible Default of `/root/.ansible_async/`. + +### Secure Logging Variables + +The following Variables compliment each other. +If Both variables are not set, secure logging defaults to false. +The role defaults to False as normally the add repository task does not include sensitive information. +ah_configuration_repository_secure_logging defaults to the value of aap_configuration_secure_logging if it is not explicitly called. This allows for secure logging to be toggled for the entire suite of automation hub configuration roles with a single variable, or for the user to selectively use it. + +|Variable Name|Default Value|Required|Description| +|`ah_configuration_collection_repository_secure_logging`|`False`|no|Whether or not to include the sensitive Namespace role tasks in the log. Set this value to `True` if you will be providing your sensitive values from elsewhere.| +|`aap_configuration_secure_logging`|`False`|no|This variable enables secure logging as well, but is shared across multiple roles, see above.| + +### Asynchronous Retry Variables + +The following Variables set asynchronous retries for the role. +If neither of the retries or delay or retries are set, they will default to their respective defaults. +This allows for all items to be created, then checked that the task finishes successfully. +This also speeds up the overall role. + +|Variable Name|Default Value|Required|Description| +|`aap_configuration_async_timeout`|1000|no|This variable sets the async timeout for the role globally.| +|`ah_configuration_collection_repository_async_timeout`|`aap_configuration_async_timeout`|no|This variable sets the async timeout for the role.| +|`aap_configuration_async_retries`|50|no|This variable sets the number of retries to attempt for the role globally.| +|`ah_configuration_collection_repository_async_retries`|`aap_configuration_async_retries`|no|This variable sets the number of retries to attempt for the role.| +|`aap_configuration_loop_delay`|1000|no|This variable sets the loop_delay for the role globally.| +|`ah_configuration_collection_repository_loop_delay`|`aap_configuration_loop_delay`|no|This variable sets the loop_delay for the role.| +|`aap_configuration_async_delay`|1|no|This sets the delay between retries for the role globally.| +|`ah_configuration_collection_repository_async_delay`|`aap_configuration_async_delay`|no|This sets the delay between retries for the role.| + +## Data Structure + +### Collection Repository Variables + +|Variable Name|Default Value|Required|Type|Description| +|`name`|""|yes|str| Collection Repository name. Probably one of community, validated, rh-certified, or one you have created.| +|`description`|""|no|str|Description to use for the Collection Repository.| +|`retain_repo_versions`|0|no|int|Retain X versions of the Collection repository. Default is 0 which retains all versions.| +|`pulp_labels`|""|no|dict|Pipeline and search options for the collection repository. See additional options below for details.| +|`distribution`|""|no|dict|Distribution options for the collection repository. See additional options below for details. Most users will leave this blank| +|`private`|""|no|boolean|Make the Collection repository private.| +|`remote`|""|no|str|Remote repository name. This is used if the collections use a remote source.| +|`update`|`false`|no|bool|Wait for the Collection repository to finish syncing before returning.| +|`wait`|`true`|no|bool|Wait for the Collection repository to finish syncing before returning.| +|`interval`|1.0|no|float|The interval to request an update from Automation Hub.| +|`timeout`|""|no|int|If waiting for the project to update this will abort after this amount of seconds.| +|`state`|`present`|no|str|Desired state of the collection repository. Either `present` or `absent`.| + +#### Additional Option Variables + +```yaml +pulp_labels: + pipeline: "approved" + hide_from_search: "" +distribution: + name: "foobar" + state: present +``` + +|Variable Name|Default Value|Required|Type|Description| +|`pipeline`|""|no|str|Description to use for the Collection Repository.| +|`hide_from_search`|""|no|str|Pipeline and search options for the collection repository.| +|`name`|""|no|dict|Distribution name to use for this collection repository. Will default to repository name if not provided.| +|`state`|`absent`|no|str|Desired state of the distribution. Either `present` or `absent`.| + +### Standard Project Data Structure + +#### Yaml Example + +```yaml +ah_collection_repositories: + - name: "foobar" + description: "description of foobar repository" + pulp_labels: + pipeline: "approved" + distribution: + name: "foobar" + state: present + remote: community +``` + +## Playbook Examples + +### Standard Role Usage + +```yaml +- name: Add repository to Automation Hub + hosts: localhost + connection: local + gather_facts: false + vars: + aap_validate_certs: false + # Define following vars here, or in ah_configs/ah_auth.yml + # ah_host: ansible-ah-web-svc-test-project.example.com + pre_tasks: + - name: Include vars from ah_configs directory + ansible.builtin.include_vars: + dir: ./vars + extensions: ["yml"] + tags: + - always + roles: + - ../../collection_repository +``` + +## License + +[GPLv3+](https://github.com/ansible/galaxy_collection#licensing) diff --git a/collections/controller_configuration/hub_collection_repository_sync.md b/collections/controller_configuration/hub_collection_repository_sync.md new file mode 100644 index 0000000..91740e0 --- /dev/null +++ b/collections/controller_configuration/hub_collection_repository_sync.md @@ -0,0 +1,106 @@ +--- +layout: default +title: hub_collection_repository_sync +parent: infra.controller_configuration +--- + +# collection_repository_sync + +## Description + +An Ansible Role to sync a Collection Repository. + +## Variables + +|Variable Name|Default Value|Required|Description|Example| +|`aap_hostname`|""|yes|URL to the Ansible Automation Platform Server.|127.0.0.1| +|`aap_username`|""|no|Admin User on the Ansible Automation Platform Server. Either username / password or oauthtoken need to be specified.|| +|`aap_password`|""|no|Platform Admin User's password on the Server. This should be stored in an Ansible Vault at vars/platform-secrets.yml or elsewhere and called from a parent playbook.|| +|`aap_validate_certs`|`True`|no|Whether or not to validate the Ansible Automation Platform Server's SSL certificate.|| +|`aap_request_timeout`|`10`|no|Specify the timeout Ansible should use in requests to the Galaxy or Automation Hub host.|| +|`ah_path_prefix`|""|no|API path used to access the api. Either galaxy, automation-hub, or custom|| +|`aap_configuration_async_dir`|`null`|no|Sets the directory to write the results file for async tasks. The default value is set to `null` which uses the Ansible Default of `/root/.ansible_async/`.|| +|`ah_collection_repositories`|`see below`|yes|Data structure describing your collection remote repository, described below.|| + +The `aap_configuration_async_dir` variable sets the directory to write the results file for async tasks. +The default value is set to `null` which uses the Ansible Default of `/root/.ansible_async/`. + +### Secure Logging Variables + +The following Variables compliment each other. +If Both variables are not set, secure logging defaults to false. +The role defaults to False as normally the add repository task does not include sensitive information. +ah_configuration_repository_secure_logging defaults to the value of aap_configuration_secure_logging if it is not explicitly called. This allows for secure logging to be toggled for the entire suite of automation hub configuration roles with a single variable, or for the user to selectively use it. + +|Variable Name|Default Value|Required|Description| +|`ah_configuration_collection_repository_sync_secure_logging`|`False`|no|Whether or not to include the sensitive Namespace role tasks in the log. Set this value to `True` if you will be providing your sensitive values from elsewhere.| +|`aap_configuration_secure_logging`|`False`|no|This variable enables secure logging as well, but is shared across multiple roles, see above.| + +### Asynchronous Retry Variables + +The following Variables set asynchronous retries for the role. +If neither of the retries or delay or retries are set, they will default to their respective defaults. +This allows for all items to be created, then checked that the task finishes successfully. +This also speeds up the overall role. + +|Variable Name|Default Value|Required|Description| +|`aap_configuration_async_timeout`|1000|no|This variable sets the async timeout for the role globally.| +|`ah_configuration_collection_repository_sync_async_timeout`|`aap_configuration_async_timeout`|no|This variable sets the async timeout for the role.| +|`aap_configuration_async_retries`|50|no|This variable sets the number of retries to attempt for the role globally.| +|`ah_configuration_collection_repository_sync_async_retries`|`aap_configuration_async_retries`|no|This variable sets the number of retries to attempt for the role.| +|`aap_configuration_loop_delay`|1000|no|This variable sets the loop_delay for the role globally.| +|`ah_configuration_collection_repository_sync_loop_delay`|`aap_configuration_loop_delay`|no|This variable sets the loop_delay for the role.| +|`aap_configuration_async_delay`|1|no|This sets the delay between retries for the role globally.| +|`ah_configuration_collection_repository_sync_async_delay`|`aap_configuration_async_delay`|no|This sets the delay between retries for the role.| + +## Data Structure + +### Collection Repository Variables + +|Variable Name|Default Value|Required|Type|Description| +|`name`|""|yes|str| Collection Repository name. Probably one of community, validated, rh-certified, or one you have created.| +|`wait`|`true`|no|bool|Wait for the Collection repository to finish syncing before returning.| +|`interval`|1.0|no|float|The interval to request an update from Automation Hub.| +|`timeout`|""|no|int|If waiting for the repository to update this will abort after this amount of seconds.| +|`state`|`present`|no|str|Desired state of the collection repository. Either `present` or `absent`.| + +### Standard Project Data Structure + +#### Yaml Example + +```yaml +ah_collection_repositories: + - name: rh-certified + wait: false + - name: community + wait: true + timeout: 60 +``` + +## Playbook Examples + +### Standard Role Usage + +```yaml +- name: Sync repository to Automation Hub + hosts: localhost + connection: local + gather_facts: false + vars: + aap_validate_certs: false + # Define following vars here, or in ah_configs/ah_auth.yml + # ah_host: ansible-ah-web-svc-test-project.example.com + pre_tasks: + - name: Include vars from ah_configs directory + ansible.builtin.include_vars: + dir: ./vars + extensions: ["yml"] + tags: + - always + roles: + - ../../collection_repository_sync +``` + +## License + +[GPLv3+](https://github.com/ansible/galaxy_collection#licensing) diff --git a/collections/controller_configuration/hub_ee_image.md b/collections/controller_configuration/hub_ee_image.md new file mode 100644 index 0000000..fdd2639 --- /dev/null +++ b/collections/controller_configuration/hub_ee_image.md @@ -0,0 +1,108 @@ +--- +layout: default +title: hub_ee_image +parent: infra.controller_configuration +--- + +# galaxy.galaxy.ee_image + +## Description + +An Ansible Role to create execution environment images in Automation Hub. + +## Variables + +|Variable Name|Default Value|Required|Description|Example| +|`aap_hostname`|""|yes|URL to the Ansible Automation Platform Server.|127.0.0.1| +|`aap_username`|""|no|Admin User on the Ansible Automation Platform Server. Either username / password or oauthtoken need to be specified.|| +|`aap_password`|""|no|Platform Admin User's password on the Server. This should be stored in an Ansible Vault at vars/platform-secrets.yml or elsewhere and called from a parent playbook.|| +|`aap_validate_certs`|`True`|no|Whether or not to validate the Ansible Automation Platform Server's SSL certificate.|| +|`aap_request_timeout`|`10`|no|Specify the timeout Ansible should use in requests to the Galaxy or Automation Hub host.|| +|`ah_path_prefix`|""|no|API path used to access the api. Either galaxy, automation-hub, or custom|| +|`aap_configuration_async_dir`|`null`|no|Sets the directory to write the results file for async tasks. The default value is set to `null` which uses the Ansible Default of `/root/.ansible_async/`.|| +|`ah_ee_images`|`see below`|yes|Data structure describing your execution environment images, described below.|| + +### Secure Logging Variables + +The following Variables compliment each other. +If Both variables are not set, secure logging defaults to false. +The role defaults to False as normally the add ee_image task does not include sensitive information. +ah_configuration_ee_image_secure_logging defaults to the value of aap_configuration_secure_logging if it is not explicitly called. This allows for secure logging to be toggled for the entire suite of automation hub configuration roles with a single variable, or for the user to selectively use it. + +|Variable Name|Default Value|Required|Description| +|`ah_configuration_ee_image_secure_logging`|`False`|no|Whether or not to include the sensitive Namespace role tasks in the log. Set this value to `True` if you will be providing your sensitive values from elsewhere.| +|`aap_configuration_secure_logging`|`False`|no|This variable enables secure logging as well, but is shared across multiple roles, see above.| + +### Asynchronous Retry Variables + +The following Variables set asynchronous retries for the role. +If neither of the retries or delay or retries are set, they will default to their respective defaults. +This allows for all items to be created, then checked that the task finishes successfully. +This also speeds up the overall role. + +|Variable Name|Default Value|Required|Description| +|`aap_configuration_async_timeout`|1000|no|This variable sets the async timeout for the role globally.| +|`ah_configuration_ee_image_async_timeout`|`aap_configuration_async_timeout`|no|This variable sets the async timeout for the role.| +|`aap_configuration_async_retries`|50|no|This variable sets the number of retries to attempt for the role globally.| +|`ah_configuration_ee_image_async_retries`|`aap_configuration_async_retries`|no|This variable sets the number of retries to attempt for the role.| +|`aap_configuration_loop_delay`|1000|no|This variable sets the loop_delay for the role globally.| +|`ah_configuration_ee_image_loop_delay`|`aap_configuration_loop_delay`|no|This variable sets the loop_delay for the role.| +|`aap_configuration_async_delay`|1|no|This sets the delay between retries for the role globally.| +|`ah_configuration_ee_image_async_delay`|`aap_configuration_async_delay`|no|This sets the delay between retries for the role.| + +## Data Structure + +### EE Image Variables + +|Variable Name|Default Value|Required|Type|Description| +|`name`|""|yes|str|Execution environment image name. Must be lower case containing only alphanumeric characters and underscores.| +|`append`|`true`|no|bool|Whether to append or replace the tags specified to the image.| +|`tags`|""|no|str|List of the image tags to update.| +|`state`|`present`|no|str|Desired state of the ee_image. (Possible values of `present` or `absent`)| + +### Standard Project Data Structure + +#### Yaml Example + +```yaml +ah_ee_images: + - name: ansible-automation-platform-20-early-access/ee-supported-rhel8:2.0.0-15 + state: present + append: false + tags: + - v2 + - "2.0" + - prod1 +``` + +## Playbook Examples + +### Standard Role Usage + +```yaml +- name: Add ee_image to Automation Hub + hosts: localhost + connection: local + gather_facts: false + vars: + aap_validate_certs: false + # Define following vars here, or in ah_configs/ah_auth.yml + # ah_host: ansible-ah-web-svc-test-project.example.com + pre_tasks: + - name: Include vars from ah_configs directory + ansible.builtin.include_vars: + dir: ./vars + extensions: ["yml"] + tags: + - always + roles: + - ../../ee_image +``` + +## License + +[GPLv3+](https://github.com/ansible/galaxy_collection#licensing) + +## Author + +[Tom Page](https://github.com/Tompage1994/) diff --git a/collections/controller_configuration/hub_ee_registry.md b/collections/controller_configuration/hub_ee_registry.md new file mode 100644 index 0000000..f7e46f9 --- /dev/null +++ b/collections/controller_configuration/hub_ee_registry.md @@ -0,0 +1,111 @@ +--- +layout: default +title: hub_ee_registry +parent: infra.controller_configuration +--- + +# galaxy.galaxy.ee_registry + +## Description + +An Ansible Role to create EE Registries in Automation Hub. + +## Variables + +|Variable Name|Default Value|Required|Description|Example| +|`aap_hostname`|""|yes|URL to the Ansible Automation Platform Server.|127.0.0.1| +|`aap_username`|""|no|Admin User on the Ansible Automation Platform Server. Either username / password or oauthtoken need to be specified.|| +|`aap_password`|""|no|Platform Admin User's password on the Server. This should be stored in an Ansible Vault at vars/platform-secrets.yml or elsewhere and called from a parent playbook.|| +|`aap_validate_certs`|`True`|no|Whether or not to validate the Ansible Automation Platform Server's SSL certificate.|| +|`aap_request_timeout`|`10`|no|Specify the timeout Ansible should use in requests to the Galaxy or Automation Hub host.|| +|`ah_path_prefix`|""|no|API path used to access the api. Either galaxy, automation-hub, or custom|| +|`aap_configuration_async_dir`|`null`|no|Sets the directory to write the results file for async tasks. The default value is set to `null` which uses the Ansible Default of `/root/.ansible_async/`.|| +|`proxy_url`|""|no|str|The URL for the proxy. Defaults to global `proxy_url` variable.| +|`proxy_username`|""|no|str|The username for the proxy authentication. Defaults to global `proxy_username` variable.| +|`proxy_password`|""|no|str|The password for the proxy authentication. Defaults to global `proxy_password` variable.| +|`ah_ee_registries`|`see below`|yes|Data structure describing your ee_registries, described below.|| + +### Secure Logging Variables + +The following Variables compliment each other. +If Both variables are not set, secure logging defaults to false. +The role defaults to False as normally the add ee_registry task does not include sensitive information. +ah_configuration_ee_registry_secure_logging defaults to the value of aap_configuration_secure_logging if it is not explicitly called. This allows for secure logging to be toggled for the entire suite of automation hub configuration roles with a single variable, or for the user to selectively use it. + +|Variable Name|Default Value|Required|Description| +|`ah_configuration_ee_registry_secure_logging`|`False`|no|Whether or not to include the sensitive Registry role tasks in the log. Set this value to `True` if you will be providing your sensitive values from elsewhere.| +|`aap_configuration_secure_logging`|`False`|no|This variable enables secure logging as well, but is shared across multiple roles, see above.| + +### Asynchronous Retry Variables + +The following Variables set asynchronous retries for the role. +If neither of the retries or delay or retries are set, they will default to their respective defaults. +This allows for all items to be created, then checked that the task finishes successfully. +This also speeds up the overall role. + +|Variable Name|Default Value|Required|Description| +|`aap_configuration_async_timeout`|1000|no|This variable sets the async timeout for the role globally.| +|`ah_configuration_ee_registry_async_timeout`|`aap_configuration_async_timeout`|no|This variable sets the async timeout for the role.| +|`aap_configuration_async_retries`|50|no|This variable sets the number of retries to attempt for the role globally.| +|`ah_configuration_ee_registry_async_retries`|`aap_configuration_async_retries`|no|This variable sets the number of retries to attempt for the role.| +|`aap_configuration_loop_delay`|1000|no|This variable sets the loop_delay for the role globally.| +|`ah_configuration_ee_registry_loop_delay`|`aap_configuration_loop_delay`|no|This variable sets the loop_delay for the role.| +|`aap_configuration_async_delay`|1|no|This sets the delay between retries for the role globally.| +|`ah_configuration_ee_registry_async_delay`|`aap_configuration_async_delay`|no|This sets the delay between retries for the role.| + +## Data Structure + +### EE Registry Variables + +|Variable Name|Default Value|Required|Type|Description| +|`name`|""|yes|str|Registry name. Must be lower case containing only alphanumeric characters and underscores.| +|`new_name`|""|no|str|Setting this option will change the existing name (looked up via the name field.| +|`url`|""|yes|str|The URL for the registry| +|`username`|""|no|str|The username for authentication to the registry| +|`password`|""|no|str|The password for authentication to the registry| +|`tls_validation`|""|no|str|Whether to use TLS when connecting to the registry| +|`download_concurrency`|""|no|str|Number of concurrent collections to download| +|`rate_limit`|""|no|str|Limits total download rate in requests per second.| +|`state`|`present`|no|str|Desired state of the ee_registry.| + +### Standard Project Data Structure + +#### Yaml Example + +```yaml +ah_ee_registries: + - name: myreg + url: https://quay.io/my/registry +``` + +## Playbook Examples + +### Standard Role Usage + +```yaml +- name: Add ee_registry to Automation Hub + hosts: localhost + connection: local + gather_facts: false + vars: + aap_validate_certs: false + # Define following vars here, or in ah_configs/ah_auth.yml + # ah_host: ansible-ah-web-svc-test-project.example.com + pre_tasks: + - name: Include vars from ah_configs directory + ansible.builtin.include_vars: + dir: ./vars + extensions: ["yml"] + tags: + - always + roles: + - ../../ee_registry +``` + +## License + +[GPLv3+](https://github.com/ansible/galaxy_collection#licensing) + +## Author + +[Tom Page](https://github.com/Tompage1994/) diff --git a/collections/controller_configuration/hub_ee_registry_index.md b/collections/controller_configuration/hub_ee_registry_index.md new file mode 100644 index 0000000..5c2212a --- /dev/null +++ b/collections/controller_configuration/hub_ee_registry_index.md @@ -0,0 +1,107 @@ +--- +layout: default +title: hub_ee_registry_index +parent: infra.controller_configuration +--- + +# galaxy.galaxy.ee_registry_index + +## Description + +An Ansible Role to index EE Registries in Automation Hub. + +## Variables + +|Variable Name|Default Value|Required|Description|Example| +|`aap_hostname`|""|yes|URL to the Ansible Automation Platform Server.|127.0.0.1| +|`aap_username`|""|no|Admin User on the Ansible Automation Platform Server. Either username / password or oauthtoken need to be specified.|| +|`aap_password`|""|no|Platform Admin User's password on the Server. This should be stored in an Ansible Vault at vars/platform-secrets.yml or elsewhere and called from a parent playbook.|| +|`aap_validate_certs`|`True`|no|Whether or not to validate the Ansible Automation Platform Server's SSL certificate.|| +|`aap_request_timeout`|`10`|no|Specify the timeout Ansible should use in requests to the Galaxy or Automation Hub host.|| +|`ah_path_prefix`|""|no|API path used to access the api. Either galaxy, automation-hub, or custom|| +|`aap_configuration_async_dir`|`null`|no|Sets the directory to write the results file for async tasks. The default value is set to `null` which uses the Ansible Default of `/root/.ansible_async/`.|| +|`ah_ee_registries`|`see below`|yes|Data structure describing your ee_registries, described below. (Note this is the same as for the `ee_registries` role and the variable can be combined). Note that this role will only do anything if the `index` suboption of this variable is set to true.|| + +### Secure Logging Variables + +The following Variables compliment each other. +If Both variables are not set, secure logging defaults to false. +The role defaults to False as normally the add ee_registry task does not include sensitive information. +ah_configuration_ee_registry_secure_logging defaults to the value of aap_configuration_secure_logging if it is not explicitly called. This allows for secure logging to be toggled for the entire suite of automation hub configuration roles with a single variable, or for the user to selectively use it. + +|Variable Name|Default Value|Required|Description| +|`ah_configuration_ee_registry_secure_logging`|`False`|no|Whether or not to include the sensitive Registry role tasks in the log. Set this value to `True` if you will be providing your sensitive values from elsewhere.| +|`aap_configuration_secure_logging`|`False`|no|This variable enables secure logging as well, but is shared across multiple roles, see above.| + +### Asynchronous Retry Variables + +The following Variables set asynchronous retries for the role. +If neither of the retries or delay or retries are set, they will default to their respective defaults. +This allows for all items to be created, then checked that the task finishes successfully. +This also speeds up the overall role. + +|Variable Name|Default Value|Required|Description| +|`aap_configuration_async_timeout`|1000|no|This variable sets the async timeout for the role globally.| +|`ah_configuration_ee_registry_index_async_timeout`|`aap_configuration_async_timeout`|no|This variable sets the async timeout for the role.| +|`aap_configuration_async_retries`|50|no|This variable sets the number of retries to attempt for the role globally.| +|`ah_configuration_ee_registry_index_async_retries`|`aap_configuration_async_retries`|no|This variable sets the number of retries to attempt for the role.| +|`aap_configuration_loop_delay`|1000|no|This variable sets the loop_delay for the role globally.| +|`ah_configuration_ee_registry_index_loop_delay`|`aap_configuration_loop_delay`|no|This variable sets the loop_delay for the role.| +|`aap_configuration_async_delay`|1|no|This sets the delay between retries for the role globally.| +|`ah_configuration_ee_registry_index_async_delay`|`aap_configuration_async_delay`|no|This sets the delay between retries for the role.| + +## Data Structure + +### EE Registry Variables + +|Variable Name|Default Value|Required|Type|Description| +|`name`|""|yes|str|Registry name. Must be lower case containing only alphanumeric characters and underscores.| +|`index`|false|no|bool|Whether to index the ee_registry. Bu default it will not index unless this is set to true.| +|`wait`|true|no|str|Whether to wait for the indexing to complete| +|`interval`|`ah_configuration_ee_registry_index_async_delay`|no|str|The interval which the indexing task will be checked for completion| +|`timeout`|""|no|str|How long to wait for the indexing task to complete| + +### Standard Project Data Structure + +#### Yaml Example + +```yaml +ah_ee_registries: + - name: myreg + url: https://quay.io/my/registry + interval: 10 + wait: true + timeout: 300 +``` + +## Playbook Examples + +### Standard Role Usage + +```yaml +- name: Index ee_registry in Automation Hub + hosts: localhost + connection: local + gather_facts: false + vars: + aap_validate_certs: false + # Define following vars here, or in ah_configs/ah_auth.yml + # ah_host: ansible-ah-web-svc-test-project.example.com + pre_tasks: + - name: Include vars from ah_configs directory + ansible.builtin.include_vars: + dir: ./vars + extensions: ["yml"] + tags: + - always + roles: + - ee_registry_index +``` + +## License + +[GPLv3+](https://github.com/ansible/galaxy_collection#licensing) + +## Author + +[Tom Page](https://github.com/Tompage1994/) diff --git a/collections/controller_configuration/hub_ee_registry_sync.md b/collections/controller_configuration/hub_ee_registry_sync.md new file mode 100644 index 0000000..61cb021 --- /dev/null +++ b/collections/controller_configuration/hub_ee_registry_sync.md @@ -0,0 +1,107 @@ +--- +layout: default +title: hub_ee_registry_sync +parent: infra.controller_configuration +--- + +# galaxy.galaxy.ee_registry_sync + +## Description + +An Ansible Role to sync EE Registries in Automation Hub. + +## Variables + +|Variable Name|Default Value|Required|Description|Example| +|`aap_hostname`|""|yes|URL to the Ansible Automation Platform Server.|127.0.0.1| +|`aap_username`|""|no|Admin User on the Ansible Automation Platform Server. Either username / password or oauthtoken need to be specified.|| +|`aap_password`|""|no|Platform Admin User's password on the Server. This should be stored in an Ansible Vault at vars/platform-secrets.yml or elsewhere and called from a parent playbook.|| +|`aap_validate_certs`|`True`|no|Whether or not to validate the Ansible Automation Platform Server's SSL certificate.|| +|`aap_request_timeout`|`10`|no|Specify the timeout Ansible should use in requests to the Galaxy or Automation Hub host.|| +|`ah_path_prefix`|""|no|API path used to access the api. Either galaxy, automation-hub, or custom|| +|`aap_configuration_async_dir`|`null`|no|Sets the directory to write the results file for async tasks. The default value is set to `null` which uses the Ansible Default of `/root/.ansible_async/`.|| +|`ah_ee_registries`|`see below`|yes|Data structure describing your ee_registries, described below. (Note this is the same as for the `ee_registries` role and the variable can be combined. Note that this role will only do anything if the `sync` suboption of this variable is set to true.|| + +### Secure Logging Variables + +The following Variables compliment each other. +If Both variables are not set, secure logging defaults to false. +The role defaults to False as normally the add ee_registry task does not include sensitive information. +ah_configuration_ee_registry_secure_logging defaults to the value of aap_configuration_secure_logging if it is not explicitly called. This allows for secure logging to be toggled for the entire suite of automation hub configuration roles with a single variable, or for the user to selectively use it. + +|Variable Name|Default Value|Required|Description| +|`ah_configuration_ee_registry_secure_logging`|`False`|no|Whether or not to include the sensitive Registry role tasks in the log. Set this value to `True` if you will be providing your sensitive values from elsewhere.| +|`aap_configuration_secure_logging`|`False`|no|This variable enables secure logging as well, but is shared across multiple roles, see above.| + +### Asynchronous Retry Variables + +The following Variables set asynchronous retries for the role. +If neither of the retries or delay or retries are set, they will default to their respective defaults. +This allows for all items to be created, then checked that the task finishes successfully. +This also speeds up the overall role. + +|Variable Name|Default Value|Required|Description| +|`aap_configuration_async_timeout`|1000|no|This variable sets the async timeout for the role globally.| +|`ah_configuration_ee_repository_sync_async_timeout`|`aap_configuration_async_timeout`|no|This variable sets the async timeout for the role.| +|`aap_configuration_async_retries`|50|no|This variable sets the number of retries to attempt for the role globally.| +|`ah_configuration_ee_registry_sync_async_retries`|`aap_configuration_async_retries`|no|This variable sets the number of retries to attempt for the role.| +|`aap_configuration_loop_delay`|1000|no|This variable sets the loop_delay for the role globally.| +|`ah_configuration_registry_sync_loop_delay`|`aap_configuration_loop_delay`|no|This variable sets the loop_delay for the role.| +|`aap_configuration_async_delay`|1|no|This sets the delay between retries for the role globally.| +|`ah_configuration_ee_registry_sync_async_delay`|`aap_configuration_async_delay`|no|This sets the delay between retries for the role.| + +## Data Structure + +### Registry Variables + +|Variable Name|Default Value|Required|Type|Description| +|`name`|""|yes|str|Registry name. Must be lower case containing only alphanumeric characters and underscores.| +|`sync`|false|no|bool|Whether to sync the ee_registry. By default it will not sync unless this is set to true.| +|`wait`|true|no|str|Whether to wait for the sync to complete| +|`interval`|`ah_configuration_ee_registry_sync_async_delay`|no|str|The interval which the sync task will be checked for completion| +|`timeout`|""|no|str|How long to wait for the sync task to complete| + +### Standard Project Data Structure + +#### Yaml Example + +```yaml +ah_ee_registries: + - name: myreg + url: https://quay.io/my/registry + interval: 10 + wait: true + timeout: 300 +``` + +## Playbook Examples + +### Standard Role Usage + +```yaml +- name: Sync ee_registry in Automation Hub + hosts: localhost + connection: local + gather_facts: false + vars: + aap_validate_certs: false + # Define following vars here, or in ah_configs/ah_auth.yml + # ah_host: ansible-ah-web-svc-test-project.example.com + pre_tasks: + - name: Include vars from ah_configs directory + ansible.builtin.include_vars: + dir: ./vars + extensions: ["yml"] + tags: + - always + roles: + - ee_registry_sync +``` + +## License + +[GPLv3+](https://github.com/ansible/galaxy_collection#licensing) + +## Author + +[Tom Page](https://github.com/Tompage1994/) diff --git a/collections/controller_configuration/hub_ee_repository.md b/collections/controller_configuration/hub_ee_repository.md new file mode 100644 index 0000000..735eaf6 --- /dev/null +++ b/collections/controller_configuration/hub_ee_repository.md @@ -0,0 +1,109 @@ +--- +layout: default +title: hub_ee_repository +parent: infra.controller_configuration +--- + +# galaxy.galaxy.ee_repository + +## Description + +An Ansible Role to create Repositories in Automation Hub. + +## Variables + +|Variable Name|Default Value|Required|Description|Example| +|`aap_hostname`|""|yes|URL to the Ansible Automation Platform Server.|127.0.0.1| +|`aap_username`|""|no|Admin User on the Ansible Automation Platform Server. Either username / password or oauthtoken need to be specified.|| +|`aap_password`|""|no|Platform Admin User's password on the Server. This should be stored in an Ansible Vault at vars/platform-secrets.yml or elsewhere and called from a parent playbook.|| +|`aap_validate_certs`|`True`|no|Whether or not to validate the Ansible Automation Platform Server's SSL certificate.|| +|`aap_request_timeout`|`10`|no|Specify the timeout Ansible should use in requests to the Galaxy or Automation Hub host.|| +|`ah_path_prefix`|""|no|API path used to access the api. Either galaxy, automation-hub, or custom|| +|`aap_configuration_async_dir`|`null`|no|Sets the directory to write the results file for async tasks. The default value is set to `null` which uses the Ansible Default of `/root/.ansible_async/`.|| +|`ah_ee_repositories`|`see below`|yes|Data structure describing your ee_repositories, described below.|| + +### Secure Logging Variables + +The following Variables compliment each other. +If Both variables are not set, secure logging defaults to false. +The role defaults to False as normally the add ee_repository task does not include sensitive information. +ah_configuration_ee_repository_secure_logging defaults to the value of aap_configuration_secure_logging if it is not explicitly called. This allows for secure logging to be toggled for the entire suite of automation hub configuration roles with a single variable, or for the user to selectively use it. + +|Variable Name|Default Value|Required|Description| +|`ah_configuration_ee_repository_secure_logging`|`False`|no|Whether or not to include the sensitive Namespace role tasks in the log. Set this value to `True` if you will be providing your sensitive values from elsewhere.| +|`aap_configuration_secure_logging`|`False`|no|This variable enables secure logging as well, but is shared across multiple roles, see above.| + +### Asynchronous Retry Variables + +The following Variables set asynchronous retries for the role. +If neither of the retries or delay or retries are set, they will default to their respective defaults. +This allows for all items to be created, then checked that the task finishes successfully. +This also speeds up the overall role. + +|Variable Name|Default Value|Required|Description| +|`aap_configuration_async_timeout`|1000|no|This variable sets the async timeout for the role globally.| +|`ah_configuration_ee_repository_async_timeout`|`aap_configuration_async_timeout`|no|This variable sets the async timeout for the role.| +|`aap_configuration_async_retries`|50|no|This variable sets the number of retries to attempt for the role globally.| +|`ah_configuration_ee_repository_async_retries`|`aap_configuration_async_retries`|no|This variable sets the number of retries to attempt for the role.| +|`aap_configuration_loop_delay`|1000|no|This variable sets the loop_delay for the role globally.| +|`ah_configuration_ee_registry_sync_loop_delay`|`aap_configuration_loop_delay`|no|This variable sets the loop_delay for the role.| +|`aap_configuration_async_delay`|1|no|This sets the delay between retries for the role globally.| +|`ah_configuration_ee_repository_async_delay`|`aap_configuration_async_delay`|no|This sets the delay between retries for the role.| + +## Data Structure + +### Repository Variables + +|Variable Name|Default Value|Required|Type|Description| +|`name`|""|yes|str|Repository name. Must be lower case containing only alphanumeric characters and underscores.| +|`description`|""|yes|str|Description to use for the Repository.| +|`readme`|""|no|str|The readme for the ee repository. (mutex with readme_file)| +|`readme_file`|""|no|str|The file location for the readme for the ee repository. (mutex with readme)| +|`state`|`present`|no|str|Desired state of the ee_repository.| +|`registry`|""|no|str|The remote registry that the repository belongs in.| +|`upstream_name`|""|no|str|The name of the image upstream.| +|`include_tags`|""|no|str|The tags to pull in.| +|`exclude_tags`|""|no|str|The tags to avoid pulling in.| + +### Standard Project Data Structure + +#### Yaml Example + +```yaml +ah_ee_repositories: + - name: abc15 + description: string + readme: "# My ee repo" +``` + +## Playbook Examples + +### Standard Role Usage + +```yaml +- name: Add ee_repository to Automation Hub + hosts: localhost + connection: local + gather_facts: false + vars: + aap_validate_certs: false + # Define following vars here, or in ah_configs/ah_auth.yml + # ah_host: ansible-ah-web-svc-test-project.example.com + pre_tasks: + - name: Include vars from ah_configs directory + ansible.builtin.include_vars: + dir: ./vars + extensions: ["yml"] + tags: + - always + roles: + - ../../ee_repository +``` + +## License + +[GPLv3+](https://github.com/ansible/galaxy_collection#licensing) + +## Author + +[Tom Page](https://github.com/Tompage1994/) diff --git a/collections/controller_configuration/hub_ee_repository_sync.md b/collections/controller_configuration/hub_ee_repository_sync.md new file mode 100644 index 0000000..b08b8f0 --- /dev/null +++ b/collections/controller_configuration/hub_ee_repository_sync.md @@ -0,0 +1,107 @@ +--- +layout: default +title: hub_ee_repository_sync +parent: infra.controller_configuration +--- + +# galaxy.galaxy.ee_repository_sync + +## Description + +An Ansible Role to sync EE Repositories in Automation Hub. + +## Variables + +|Variable Name|Default Value|Required|Description|Example| +|`aap_hostname`|""|yes|URL to the Ansible Automation Platform Server.|127.0.0.1| +|`aap_username`|""|no|Admin User on the Ansible Automation Platform Server. Either username / password or oauthtoken need to be specified.|| +|`aap_password`|""|no|Platform Admin User's password on the Server. This should be stored in an Ansible Vault at vars/platform-secrets.yml or elsewhere and called from a parent playbook.|| +|`aap_validate_certs`|`True`|no|Whether or not to validate the Ansible Automation Platform Server's SSL certificate.|| +|`aap_request_timeout`|`10`|no|Specify the timeout Ansible should use in requests to the Galaxy or Automation Hub host.|| +|`ah_path_prefix`|""|no|API path used to access the api. Either galaxy, automation-hub, or custom|| +|`aap_configuration_async_dir`|`null`|no|Sets the directory to write the results file for async tasks. The default value is set to `null` which uses the Ansible Default of `/root/.ansible_async/`.|| +|`ah_ee_repositories`|`see below`|yes|Data structure describing your ee_repositories, described below. (Note this is the same as for the `ee_repository` role and the variable can be combined. Note that this role will only do anything if the `sync` suboption of this variable is set to true.|| + +### Secure Logging Variables + +The following Variables compliment each other. +If Both variables are not set, secure logging defaults to false. +The role defaults to False as normally the add ee_repository task does not include sensitive information. +ah_configuration_ee_repository_secure_logging defaults to the value of aap_configuration_secure_logging if it is not explicitly called. This allows for secure logging to be toggled for the entire suite of automation hub configuration roles with a single variable, or for the user to selectively use it. + +|Variable Name|Default Value|Required|Description| +|`ah_configuration_ee_repository_secure_logging`|`False`|no|Whether or not to include the sensitive Repository role tasks in the log. Set this value to `True` if you will be providing your sensitive values from elsewhere.| +|`aap_configuration_secure_logging`|`False`|no|This variable enables secure logging as well, but is shared across multiple roles, see above.| + +### Asynchronous Retry Variables + +The following Variables set asynchronous retries for the role. +If neither of the retries or delay or retries are set, they will default to their respective defaults. +This allows for all items to be created, then checked that the task finishes successfully. +This also speeds up the overall role. + +|Variable Name|Default Value|Required|Description| +|`aap_configuration_async_timeout`|1000|no|This variable sets the async timeout for the role globally.| +|`ah_configuration_ee_repository_sync_async_timeout`|`aap_configuration_async_timeout`|no|This variable sets the async timeout for the role.| +|`aap_configuration_async_retries`|50|no|This variable sets the number of retries to attempt for the role globally.| +|`ah_configuration_ee_repository_sync_async_retries`|`aap_configuration_async_retries`|no|This variable sets the number of retries to attempt for the role.| +|`aap_configuration_loop_delay`|1000|no|This variable sets the loop_delay for the role globally.| +|`ah_configuration_ee_repository_sync_loop_delay`|`aap_configuration_loop_delay`|no|This variable sets the loop_delay for the role.| +|`aap_configuration_async_delay`|1|no|This sets the delay between retries for the role globally.| +|`ah_configuration_ee_repository_sync_async_delay`|`aap_configuration_async_delay`|no|This sets the delay between retries for the role.| + +## Data Structure + +### Repository Variables + +|Variable Name|Default Value|Required|Type|Description| +|`name`|""|yes|str|Repository name. Must be lower case containing only alphanumeric characters and underscores.| +|`sync`|false|no|bool|Whether to sync the ee_registry. By default it will not sync unless this is set to true.| +|`wait`|true|no|str|Whether to wait for the sync to complete| +|`interval`|`ah_configuration_ee_repository_sync_async_delay`|no|str|The interval which the sync task will be checked for completion| +|`timeout`|""|no|str|How long to wait for the sync task to complete| + +### Standard Project Data Structure + +#### Yaml Example + +```yaml +ah_ee_repositories: + - name: abc15 + description: string + readme: "# My EE repository" + wait: true + interval: 10 +``` + +## Playbook Examples + +### Standard Role Usage + +```yaml +- name: Sync ee_repository in Automation Hub + hosts: localhost + connection: local + gather_facts: false + vars: + aap_validate_certs: false + # Define following vars here, or in ah_configs/ah_auth.yml + # ah_host: ansible-ah-web-svc-test-project.example.com + pre_tasks: + - name: Include vars from ah_configs directory + ansible.builtin.include_vars: + dir: ./vars + extensions: ["yml"] + tags: + - always + roles: + - ee_repository_sync +``` + +## License + +[GPLv3+](https://github.com/ansible/galaxy_collection#licensing) + +## Author + +[Tom Page](https://github.com/Tompage1994/) diff --git a/collections/controller_configuration/hub_group.md b/collections/controller_configuration/hub_group.md new file mode 100644 index 0000000..8889124 --- /dev/null +++ b/collections/controller_configuration/hub_group.md @@ -0,0 +1,115 @@ +--- +layout: default +title: hub_group +parent: infra.controller_configuration +--- + +# galaxy.galaxy.group + +## Description + +An Ansible Role to create groups in Automation Hub. + +## Variables + +|Variable Name|Default Value|Required|Description|Example| +|`aap_hostname`|""|yes|URL to the Ansible Automation Platform Server.|127.0.0.1| +|`aap_username`|""|no|Admin User on the Ansible Automation Platform Server. Either username / password or oauthtoken need to be specified.|| +|`aap_password`|""|no|Platform Admin User's password on the Server. This should be stored in an Ansible Vault at vars/platform-secrets.yml or elsewhere and called from a parent playbook.|| +|`aap_validate_certs`|`True`|no|Whether or not to validate the Ansible Automation Platform Server's SSL certificate.|| +|`aap_request_timeout`|`10`|no|Specify the timeout Ansible should use in requests to the Galaxy or Automation Hub host.|| +|`ah_path_prefix`|""|no|API path used to access the api. Either galaxy, automation-hub, or custom|| +|`aap_configuration_async_dir`|`null`|no|Sets the directory to write the results file for async tasks. The default value is set to `null` which uses the Ansible Default of `/root/.ansible_async/`.|| +|`ah_groups`|`see below`|yes|Data structure describing your groups, described below.|| + +### Secure Logging Variables + +The following Variables compliment each other. +If Both variables are not set, secure logging defaults to false. +The role defaults to False as normally the add group task does not include sensitive information. +ah_configuration_group_secure_logging defaults to the value of aap_configuration_secure_logging if it is not explicitly called. This allows for secure logging to be toggled for the entire suite of automation hub configuration roles with a single variable, or for the user to selectively use it. + +|Variable Name|Default Value|Required|Description| +|`ah_configuration_group_secure_logging`|`False`|no|Whether or not to include the sensitive Namespace role tasks in the log. Set this value to `True` if you will be providing your sensitive values from elsewhere.| +|`aap_configuration_secure_logging`|`False`|no|This variable enables secure logging as well, but is shared across multiple roles, see above.| + +### Asynchronous Retry Variables + +The following Variables set asynchronous retries for the role. +If neither of the retries or delay or retries are set, they will default to their respective defaults. +This allows for all items to be created, then checked that the task finishes successfully. +This also speeds up the overall role. + +|Variable Name|Default Value|Required|Description| +|`aap_configuration_async_retries`|50|no|This variable sets the number of retries to attempt for the role globally.| +|`ah_configuration_group_async_retries`|`aap_configuration_async_retries`|no|This variable sets the number of retries to attempt for the role.| +|`aap_configuration_loop_delay`|1000|no|This variable sets the loop_delay for the role globally.| +|`ah_configuration_group_loop_delay`|`aap_configuration_loop_delay`|no|This variable sets the loop_delay for the role.| +|`aap_configuration_async_delay`|1|no|This sets the delay between retries for the role globally.| +|`ah_configuration_group_async_delay`|`aap_configuration_async_delay`|no|This sets the delay between retries for the role.| + +## Data Structure + +### Group Variables + +|Variable Name|Default Value|Required|Type|Description| +|`name`|""|yes|str|Group Name. Must be lower case containing only alphanumeric characters and underscores.| +|`perms`|""|yes|str|The list of permissions to add to or remove from the given group. See below for options.| +|`state`|`present`|no|str|Desired state of the group.| + +#### perms + +The module accepts the following roles: + +- For user management, `add_user`, `change_user`, `delete_user`, and `view_user`. +- For group management, `add_group`, `change_group`, `delete_group`, and `view_group`. +- For collection namespace management, `add_namespace`, `change_namespace`, `upload_to_namespace`, and `delete_namespace`. +- For collection content management, `modify_ansible_repo_content`, and `delete_collection`. +- For remote repository configuration, `change_collectionremote` and `view_collectionremote`. +- For container image management, only with private automation hub v4.3.2 + or later, `change_containernamespace_perms`, `change_container`, + `change_image_tag`, `create_container`, `push_container`, and `delete_containerrepository`. +- For task management, `change_task`, `view_task`, and `delete_task`. +- You can also grant or revoke all permissions with `*` or `all`. + +### Standard Project Data Structure + +#### Yaml Example + +```yaml +ah_groups: + - name: group1 + state: present +``` + +## Playbook Examples + +### Standard Role Usage + +```yaml +- name: Add group to Automation Hub + hosts: localhost + connection: local + gather_facts: false + vars: + aap_validate_certs: false + # Define following vars here, or in ah_configs/ah_auth.yml + # ah_host: ansible-ah-web-svc-test-project.example.com + pre_tasks: + - name: Include vars from ah_configs directory + ansible.builtin.include_vars: + dir: ./vars + extensions: ["yml"] + tags: + - always + roles: + - ../../group +``` + +## License + +[GPLv3+](https://github.com/ansible/galaxy_collection#licensing) + +## Author + +[Tom Page](https://github.com/Tompage1994/) diff --git a/collections/controller_configuration/hub_group_roles.md b/collections/controller_configuration/hub_group_roles.md new file mode 100644 index 0000000..ebe4811 --- /dev/null +++ b/collections/controller_configuration/hub_group_roles.md @@ -0,0 +1,156 @@ +--- +layout: default +title: hub_group_roles +parent: infra.controller_configuration +--- + +# group_roles + +## Description + +An Ansible Role to add roles to groups in Automation Hub. + +## Variables + +|Variable Name|Default Value|Required|Description|Example| +|`aap_hostname`|""|yes|URL to the Ansible Automation Platform Server.|127.0.0.1| +|`aap_username`|""|no|Admin User on the Ansible Automation Platform Server. Either username / password or oauthtoken need to be specified.|| +|`aap_password`|""|no|Platform Admin User's password on the Server. This should be stored in an Ansible Vault at vars/platform-secrets.yml or elsewhere and called from a parent playbook.|| +|`aap_validate_certs`|`True`|no|Whether or not to validate the Ansible Automation Platform Server's SSL certificate.|| +|`aap_request_timeout`|`10`|no|Specify the timeout Ansible should use in requests to the Galaxy or Automation Hub host.|| +|`ah_path_prefix`|""|no|API path used to access the api. Either galaxy, automation-hub, or custom|| +|`aap_configuration_async_dir`|`null`|no|Sets the directory to write the results file for async tasks. The default value is set to `null` which uses the Ansible Default of `/root/.ansible_async/`.|| +|`ah_group_roles`|`see below`|yes|Data structure describing the roles which are applied to groups, described below.|| + +### Secure Logging Variables + +The following Variables compliment each other. +If Both variables are not set, secure logging defaults to false. +The role defaults to False as normally the add group task does not include sensitive information. +ah_configuration_group_secure_logging defaults to the value of aap_configuration_secure_logging if it is not explicitly called. This allows for secure logging to be toggled for the entire suite of automation hub configuration roles with a single variable, or for the user to selectively use it. + +|Variable Name|Default Value|Required|Description| +|`ah_configuration_group_secure_logging`|`False`|no|Whether or not to include the sensitive Namespace role tasks in the log. Set this value to `True` if you will be providing your sensitive values from elsewhere.| +|`aap_configuration_secure_logging`|`False`|no|This variable enables secure logging as well, but is shared across multiple roles, see above.| + +### Asynchronous Retry Variables + +The following Variables set asynchronous retries for the role. +If neither of the retries or delay or retries are set, they will default to their respective defaults. +This allows for all items to be created, then checked that the task finishes successfully. +This also speeds up the overall role. + +|Variable Name|Default Value|Required|Description| +|`aap_configuration_async_timeout`|1000|no|This variable sets the async timeout for the role globally.| +|`ah_configuration_group_roles_async_timeout`|`aap_configuration_async_timeout`|no|This variable sets the async timeout for the role.| +|`aap_configuration_async_retries`|50|no|This variable sets the number of retries to attempt for the role globally.| +|`ah_configuration_group_roles_async_retries`|`aap_configuration_async_retries`|no|This variable sets the number of retries to attempt for the role.| +|`aap_configuration_loop_delay`|1000|no|This variable sets the loop_delay for the role globally.| +|`ah_configuration_group_roles_loop_delay`|`aap_configuration_loop_delay`|no|This variable sets the loop_delay for the role.| +|`aap_configuration_async_delay`|1|no|This sets the delay between retries for the role globally.| +|`ah_configuration_group_roles_async_delay`|`aap_configuration_async_delay`|no|This sets the delay between retries for the role.| + +## Data Structure + +### Group Variables + +|Variable Name|Default Value|Required|Type|Description| +|`groups`|""|yes|str| List of Group Names to apply the roles to. If the group does not exist, it will be created. Must be lower case containing only alphanumeric characters and underscores.| +|`role_list`|""|yes|str|The list of roles to add to or remove from the given group. See below for options.| +|`state`|`present`|no|str|Desired state of the group. Can be `present`, `enforced`, or `absent`. If absent, then the module deletes the given combination of roles for given groups. If present, then the module creates the group roles if it does not already exist. If enforced, then the module will remove any group role combinations not provided.| + +#### role_list + +The `role_list` variable is a combination of roles and targets that are applied to the groups listed in `groups`. +The structure look slike + +```yaml +- roles: + - container.containerdistribution_owner + targets: + execution_environments: + - ee-minimal-rhel8 +``` + +Roles can be those that were created using the `role` role, the `ah_role`, or the built in roles. + +If no targets are listed, the roles are applied globally to the groups. +Targets consist of the following. + +|Target|Description| +|`collection_namespaces`|List of collection namespaces to apply the roles to.| +|`collection_remotes`|List of collection remotes to apply the roles to.| +|`collection_repositories`|List of collection repositories to apply the roles to.| +|`execution_environments`|List of execution environments to apply the roles to.| +|`container_registery_remotes`|List of container registry remotes to apply the roles to.| + +#### Yaml Example + +```yaml +ah_group_roles: + - state: present + groups: + - santa + - group1 + role_list: + - roles: + - container.containerdistribution_owner + targets: + execution_environments: + - redhat_cop/config_as_code_ee + - roles: + - galaxy.container_remote + targets: + container_registery_remotes: + - quay + - roles: + - galaxy.user_admin + - galaxy.group_admin + - roles: + - galaxy.ansible_repository_owner + targets: + collection_repositories: + - validated + - roles: + - galaxy.collection_remote_owner + targets: + collection_remotes: + - community + - roles: + - galaxy.collection_namespace_owner + targets: + collection_namespaces: + - autohubtest2 +``` + +## Playbook Examples + +### Standard Role Usage + +```yaml +- name: Add group roles to Automation Hub + hosts: localhost + connection: local + gather_facts: false + vars: + aap_validate_certs: false + # Define following vars here, or in ah_configs/ah_auth.yml + # ah_host: ansible-ah-web-svc-test-project.example.com + pre_tasks: + - name: Include vars from ah_configs directory + ansible.builtin.include_vars: + dir: ./vars + extensions: ["yml"] + tags: + - always + roles: + - ../../hub_group_roles +``` + +## License + +[GPLv3+](https://github.com/ansible/galaxy_collection#licensing) + +## Author + +[Tom Page](https://github.com/Tompage1994/) diff --git a/collections/controller_configuration/hub_namespace.md b/collections/controller_configuration/hub_namespace.md new file mode 100644 index 0000000..88d6f5c --- /dev/null +++ b/collections/controller_configuration/hub_namespace.md @@ -0,0 +1,129 @@ +--- +layout: default +title: hub_namespace +parent: infra.controller_configuration +--- + +# galaxy.galaxy.namespace + +## Description + +An Ansible Role to create Namespaces in Automation Hub. + +## Variables + +|Variable Name|Default Value|Required|Description|Example| +|`aap_hostname`|""|yes|URL to the Ansible Automation Platform Server.|127.0.0.1| +|`aap_username`|""|no|Admin User on the Ansible Automation Platform Server. Either username / password or oauthtoken need to be specified.|| +|`aap_password`|""|no|Platform Admin User's password on the Server. This should be stored in an Ansible Vault at vars/platform-secrets.yml or elsewhere and called from a parent playbook.|| +|`ah_token`|""|yes|Tower Admin User's token on the Automation Hub Server. This should be stored in an Ansible Vault at or elsewhere and called from a parent playbook.|| +|`aap_validate_certs`|`True`|no|Whether or not to validate the Ansible Automation Platform Server's SSL certificate.|| +|`aap_request_timeout`|`10`|no|Specify the timeout Ansible should use in requests to the Galaxy or Automation Hub host.|| +|`ah_path_prefix`|""|no|API path used to access the api. Either galaxy, automation-hub, or custom|| +|`aap_configuration_async_dir`|`null`|no|Sets the directory to write the results file for async tasks. The default value is set to `null` which uses the Ansible Default of `/root/.ansible_async/`.|| +|`ah_namespaces`|`see below`|yes|Data structure describing your namespaces, described below.|| + +### Secure Logging Variables + +The following Variables compliment each other. +If Both variables are not set, secure logging defaults to false. +The role defaults to False as normally the add namespace task does not include sensitive information. +ah_configuration_namespace_secure_logging defaults to the value of aap_configuration_secure_logging if it is not explicitly called. This allows for secure logging to be toggled for the entire suite of automation hub configuration roles with a single variable, or for the user to selectively use it. + +|Variable Name|Default Value|Required|Description| +|`ah_configuration_namespace_secure_logging`|`False`|no|Whether or not to include the sensitive Namespace role tasks in the log. Set this value to `True` if you will be providing your sensitive values from elsewhere.| +|`aap_configuration_secure_logging`|`False`|no|This variable enables secure logging as well, but is shared across multiple roles, see above.| + +### Asynchronous Retry Variables + +The following Variables set asynchronous retries for the role. +If neither of the retries or delay or retries are set, they will default to their respective defaults. +This allows for all items to be created, then checked that the task finishes successfully. +This also speeds up the overall role. + +|Variable Name|Default Value|Required|Description| +|`aap_configuration_async_timeout`|1000|no|This variable sets the async timeout for the role globally.| +|`ah_configuration_namespace_async_timeout`|`aap_configuration_async_timeout`|no|This variable sets the async timeout for the role.| +|`aap_configuration_async_retries`|50|no|This variable sets the number of retries to attempt for the role globally.| +|`ah_configuration_namespace_async_retries`|`aap_configuration_async_retries`|no|This variable sets the number of retries to attempt for the role.| +|`aap_configuration_loop_delay`|1000|no|This variable sets the loop_delay for the role globally.| +|`ah_configuration_namespace_loop_delay`|`aap_configuration_loop_delay`|no|This variable sets the loop_delay for the role.| +|`aap_configuration_async_delay`|1|no|This sets the delay between retries for the role globally.| +|`ah_configuration_namespace_async_delay`|`aap_configuration_async_delay`|no|This sets the delay between retries for the role.| + +## Data Structure + +### Namespace Variables + +|Variable Name|Default Value|Required|Type|Description| +|`name`|""|yes|str|Namespace name. Must be lower case containing only alphanumeric characters and underscores.| +|`new_name`|""|yes|str|Setting this option will change the existing name (looked up via the name field.| +|`description`|""|yes|str|Description to use for the Namespace.| +|`company`|""|no|str|Namespace owner company name.| +|`email`|"password"|yes|str|Namespace contact email.| +|`avatar_url`|"public"|yes|str|Namespace logo URL.| +|`resources`|""|no|str|Namespace resource page in Markdown format.| +|`links`|[]|no|list|A list of dictionaries of Name and url values for links related the Namespace. See below for details.| +|`groups`|[]|yes|list|A list of dictionaries of the Names of groups that own the Namespace.| +|`state`|`present`|no|str|Desired state of the namespace.| + +#### Links + +|Variable Name|Default Value|Required|Type|Description| +|`name`|""|yes|str|Link Text.| +|`description`|""|yes|str|Link URL.| + +### Standard Project Data Structure + +#### Yaml Example + +```yaml +ah_namespaces: + - name: abc15 + company: Redhat + email: user@example.com + avatar_url: https://static.redhat.com/libs/redhat/brand-assets/latest/corp/logo.svg + description: string + resources: "# Redhat\nA Namespace test with changes" + links: + - name: "New_Google" + url: "http://www.google.com" + groups: + - name: system:partner-engineers + object_roles: + - "change_namespace" + - "upload_to_namespace" +``` + +## Playbook Examples + +### Standard Role Usage + +```yaml +- name: Add namespace to Automation Hub + hosts: localhost + connection: local + gather_facts: false + vars: + aap_validate_certs: false + # Define following vars here, or in ah_configs/ah_auth.yml + # ah_host: ansible-ah-web-svc-test-project.example.com + # ah_token: changeme + pre_tasks: + - name: Include vars from ah_configs directory + ansible.builtin.include_vars: + dir: ./vars + extensions: ["yml"] + tags: + - always + roles: + - ../../namespace +``` + +## License + +[GPLv3+](https://github.com/ansible/galaxy_collection#licensing) + +## Author + +[Sean Sullivan](https://github.com/sean-m-sullivan/) diff --git a/collections/controller_configuration/hub_publish.md b/collections/controller_configuration/hub_publish.md new file mode 100644 index 0000000..fc6c0a3 --- /dev/null +++ b/collections/controller_configuration/hub_publish.md @@ -0,0 +1,113 @@ +--- +layout: default +title: hub_publish +parent: infra.controller_configuration +--- + +# galaxy.galaxy.publish + +## Description + +An Ansible Role to publish collections to Automation Hub or Galaxies. + +## Variables + +|Variable Name|Default Value|Required|Description|Example| +|`aap_hostname`|""|yes|URL to the Ansible Automation Platform Server.|127.0.0.1| +|`aap_username`|""|no|Admin User on the Ansible Automation Platform Server. Either username / password or oauthtoken need to be specified.|| +|`aap_password`|""|no|Platform Admin User's password on the Server. This should be stored in an Ansible Vault at vars/platform-secrets.yml or elsewhere and called from a parent playbook.|| +|`ah_token`|""|no|Admin User's token on the Automation Hub Server. This should be stored in an Ansible Vault at or elsewhere and called from a parent playbook.|| +|`aap_validate_certs`|`True`|no|Whether or not to validate the Ansible Automation Platform Server's SSL certificate.|| +|`aap_request_timeout`|`10`|no|Specify the timeout Ansible should use in requests to the Galaxy or Automation Hub host.|| +|`ah_path_prefix`|""|no|API path used to access the api. Either galaxy, automation-hub, or custom|| +|`aap_configuration_async_dir`|`null`|no|Sets the directory to write the results file for async tasks. The default value is set to `null` which uses the Ansible Default of `/root/.ansible_async/`.|| +|`aap_configuration_working_dir`|`/var/tmp`|no|The working directory where the built artifacts live, or where the artifacts will be built.|| +|`ah_auto_approve`|`False`|no|Whether the collection will be automatically approved in Automation Hub. This will only work if the account being used has correct privileges.|| +|`ah_overwrite_existing`|`False`|no|Whether the collection will be automatically overwrite an existing collection in Automation Hub. This will only work if the account being used has correct privileges.|| +|`ah_collections`|`see below`|no|Data structure describing your collections, mutually exclusive to ah_collection_list, described below.|| +|`ah_collection_list`|`list`|no|Data structure file paths to pre built collections, mutually exclusive with ah_collections.|| + +### Secure Logging Variables + +The following Variables compliment each other. +If Both variables are not set, secure logging defaults to false. +The role defaults to False as normally the add publish collections task does not include sensitive information. +ah_configuration_publish_secure_logging defaults to the value of aap_configuration_secure_logging if it is not explicitly called. This allows for secure logging to be toggled for the entire suite of automation hub configuration roles with a single variable, or for the user to selectively use it. + +|Variable Name|Default Value|Required|Description| +|`ah_configuration_publish_secure_logging`|`False`|no|Whether or not to include the sensitive publish collections role tasks in the log. Set this value to `True` if you will be providing your sensitive values from elsewhere.| +|`aap_configuration_secure_logging`|`False`|no|This variable enables secure logging as well, but is shared across multiple roles, see above.| + +### Asynchronous Retry Variables + +The following Variables set asynchronous retries for the role. +If neither of the retries or delay or retries are set, they will default to their respective defaults. +This allows for all items to be created, then checked that the task finishes successfully. +This also speeds up the overall role. + +|Variable Name|Default Value|Required|Description| +|`aap_configuration_async_timeout`|1000|no|This variable sets the async timeout for the role globally.| +|`ah_configuration_publish_async_timeout`|`aap_configuration_async_timeout`|no|This variable sets the async timeout for the role.| +|`aap_configuration_async_retries`|50|no|This variable sets the number of retries to attempt for the role globally.| +|`ah_configuration_publish_async_retries`|`aap_configuration_async_retries`|no|This variable sets the number of retries to attempt for the role.| +|`aap_configuration_loop_delay`|1000|no|This variable sets the loop_delay for the role globally.| +|`ah_configuration_publish_loop_delay`|`aap_configuration_loop_delay`|no|This variable sets the loop_delay for the role.| +|`aap_configuration_async_delay`|1|no|This sets the delay between retries for the role globally.| +|`ah_configuration_publish_async_delay`|`aap_configuration_async_delay`|no|This sets the delay between retries for the role.| + +## Data Structure + +### ah_collections Variables + +|Variable Name|Default Value|Required|Type|Description| +|`collection_name`|""|yes|str|Name of collection, normally the last part before the / in a git url.| +|`git_url`|""|no|str|Url to git repo. Required if collection_local_path not set| +|`version`|""|no|str|Git ref to pull. Will default to default branch if unset. Can specify tag, branch or commit ref here.| +|`key_path`|""|no|str|Path to ssh key for authentication.| +|`ssh_opts`|""|no|str|Options git will pass to ssh when used as protocol.| +|`collection_local_path`|""|no|str|Path to collection stored locally. Required if git_url not set. This value will be used rather than git_url if set.| + +### Standard Project Data Structure + +#### Yaml Example + +```yaml +ah_collections: + - collection_name: cisco.iosxr + git_url: https://github.com/ansible-collections/cisco.iosxr + +ah_auto_approve: true +``` + +## Playbook Examples + +### Standard Role Usage + +```yaml +- name: Build and add collection to Automation Hub + hosts: localhost + connection: local + gather_facts: false + vars: + aap_validate_certs: false + # Define following vars here, or in ah_configs/ah_auth.yml + # ah_host: ansible-ah-web-svc-test-project.example.com + # ah_token: changeme + pre_tasks: + - name: Include vars from ah_configs directory + ansible.builtin.include_vars: + dir: ./vars + extensions: ["yml"] + tags: + - always + roles: + - galaxy.galaxy.publish +``` + +## License + +[GPLv3+](https://github.com/ansible/galaxy_collection#licensing) + +## Author + +[Sean Sullivan](https://github.com/sean-m-sullivan/) diff --git a/collections/controller_configuration/hub_role.md b/collections/controller_configuration/hub_role.md new file mode 100644 index 0000000..eeb852f --- /dev/null +++ b/collections/controller_configuration/hub_role.md @@ -0,0 +1,127 @@ +--- +layout: default +title: hub_role +parent: infra.controller_configuration +--- + +# galaxy.galaxy.role + +## Description + +An Ansible Role to create role permissions in Automation Hub. + +## Variables + +|Variable Name|Default Value|Required|Description|Example| +|`aap_hostname`|""|yes|URL to the Ansible Automation Platform Server.|127.0.0.1| +|`aap_username`|""|no|Admin User on the Ansible Automation Platform Server. Either username / password or oauthtoken need to be specified.|| +|`aap_password`|""|no|Platform Admin User's password on the Server. This should be stored in an Ansible Vault at vars/platform-secrets.yml or elsewhere and called from a parent playbook.|| +|`aap_validate_certs`|`True`|no|Whether or not to validate the Ansible Automation Platform Server's SSL certificate.|| +|`aap_request_timeout`|`10`|no|Specify the timeout Ansible should use in requests to the Galaxy or Automation Hub host.|| +|`ah_path_prefix`|""|no|API path used to access the api. Either galaxy, automation-hub, or custom|| +|`aap_configuration_async_dir`|`null`|no|Sets the directory to write the results file for async tasks. The default value is set to `null` which uses the Ansible Default of `/root/.ansible_async/`.|| +|`ah_roles`|`see below`|yes|Data structure describing your role permissions, described below.|| + +### Secure Logging Variables + +The following Variables compliment each other. +If Both variables are not set, secure logging defaults to false. +The role defaults to False as normally the add group task does not include sensitive information. +ah_configuration_group_secure_logging defaults to the value of aap_configuration_secure_logging if it is not explicitly called. This allows for secure logging to be toggled for the entire suite of automation hub configuration roles with a single variable, or for the user to selectively use it. + +|Variable Name|Default Value|Required|Description| +|`ah_configuration_role_secure_logging`|`False`|no|Whether or not to include the sensitive Namespace role tasks in the log. Set this value to `True` if you will be providing your sensitive values from elsewhere.| +|`aap_configuration_secure_logging`|`False`|no|This variable enables secure logging as well, but is shared across multiple roles, see above.| + +### Asynchronous Retry Variables + +The following Variables set asynchronous retries for the role. +If neither of the retries or delay or retries are set, they will default to their respective defaults. +This allows for all items to be created, then checked that the task finishes successfully. +This also speeds up the overall role. + +|Variable Name|Default Value|Required|Description| +|`aap_configuration_async_timeout`|1000|no|This variable sets the async timeout for the role globally.| +|`ah_configuration_role_async_timeout`|`aap_configuration_async_timeout`|no|This variable sets the async timeout for the role.| +|`aap_configuration_async_retries`|50|no|This variable sets the number of retries to attempt for the role globally.| +|`ah_configuration_role_async_retries`|`aap_configuration_async_retries`|no|This variable sets the number of retries to attempt for the role.| +|`aap_configuration_async_delay`|1|no|This sets the delay between retries for the role globally.| +|`ah_configuration_role_async_delay`|`aap_configuration_async_delay`|no|This sets the delay between retries for the role.| + +## Data Structure + +### Role Variables + +|Variable Name|Default Value|Required|Type|Description| +|`name`|""|yes|str|Group Name. Must be lower case containing only alphanumeric characters and underscores. Must start with 'galaxy.'.| +|`description`|""|yes|str|The description of the permission role.| +|`perms`|""|yes|str|The list of permissions for the given role. See below for options.| +|`state`|`present`|no|str|Desired state of the group.| + +#### perms + +The module accepts the following roles: + +- For user management, `add_user`, `change_user`, `delete_user`, and `view_user`. +- For group management, `add_group`, `change_group`, `delete_group`, and `view_group`. +- For collection namespace management, `add_namespace`, `change_namespace`, `upload_to_namespace`, and `delete_namespace`. +- For collection content management, `modify_ansible_repo_content`, `delete_collection`, and `sign_ansiblerepository`. +- For remote repository configuration, `change_collectionremote`, `view_collectionremote`, + `add_collectionremote`, `delete_collectionremote`, and `manage_roles_collectionremote`. +- For Ansible Repository management, only with private automation hub v4.7.0 + `add_ansiblerepository`, `change_ansiblerepository`, `delete_ansiblerepository`, `manage_roles_ansiblerepository`, + `repair_ansiblerepository`, `view_ansiblerepository`, +- For container image management, only with private automation hub v4.3.2 or later, + `change_containernamespace_perms`, `change_container`, `change_image_tag`, `create_container`, + Push existing container `push_container`, `namespace_add_containerdistribution`, `manage_roles_containernamespace`, + and `delete_containerrepository`. +- For remote registry management, `add_containerregistryremote`, `change_containerregistryremote`, and`delete_containerregistryremote`. +- For task management, `change_task`, `view_task`, and `delete_task`. +- You can also grant or revoke all permissions with `*` or `all`. + +### Standard Project Data Structure + +#### Yaml Example + +```yaml +ah_roles: + - name: galaxy.stuff.mcstuffins + description: test + perms: + - add_user + - change_user + - delete_user + - view_user +``` + +## Playbook Examples + +### Standard Role Usage + +```yaml +- name: Add roles to Automation Hub + hosts: localhost + connection: local + gather_facts: false + vars: + aap_validate_certs: false + # Define following vars here, or in ah_configs/ah_auth.yml + # ah_host: ansible-ah-web-svc-test-project.example.com + pre_tasks: + - name: Include vars from ah_configs directory + ansible.builtin.include_vars: + dir: ./vars + extensions: ["yml"] + tags: + - always + roles: + - ../../role +``` + +## License + +[GPLv3+](https://github.com/ansible/galaxy_collection#licensing) + +## Author + +[Tom Page](https://github.com/Tompage1994/) diff --git a/collections/controller_configuration/hub_user.md b/collections/controller_configuration/hub_user.md new file mode 100644 index 0000000..09fe4ac --- /dev/null +++ b/collections/controller_configuration/hub_user.md @@ -0,0 +1,117 @@ +--- +layout: default +title: hub_user +parent: infra.controller_configuration +--- + +# galaxy.galaxy.user + +## Description + +An Ansible Role to create users in Automation Hub. + +## Variables + +|Variable Name|Default Value|Required|Description|Example| +|`aap_hostname`|""|yes|URL to the Ansible Automation Platform Server.|127.0.0.1| +|`aap_username`|""|no|Admin User on the Ansible Automation Platform Server. Either username / password or oauthtoken need to be specified.|| +|`aap_password`|""|no|Platform Admin User's password on the Server. This should be stored in an Ansible Vault at vars/platform-secrets.yml or elsewhere and called from a parent playbook.|| +|`aap_validate_certs`|`True`|no|Whether or not to validate the Ansible Automation Platform Server's SSL certificate.|| +|`aap_request_timeout`|`10`|no|Specify the timeout Ansible should use in requests to the Galaxy or Automation Hub host.|| +|`ah_path_prefix`|""|no|API path used to access the api. Either galaxy, automation-hub, or custom|| +|`aap_configuration_async_dir`|`null`|no|Sets the directory to write the results file for async tasks. The default value is set to `null` which uses the Ansible Default of `/root/.ansible_async/`.|| +|`aap_user_accounts`|`see below`|yes|Data structure describing your execution environment images, described below.|| + +### Secure Logging Variables + +The following Variables compliment each other. +If Both variables are not set, secure logging defaults to false. +The role defaults to False as normally the add user task does not include sensitive information. +ah_configuration_user_secure_logging defaults to the value of aap_configuration_secure_logging if it is not explicitly called. This allows for secure logging to be toggled for the entire suite of automation hub configuration roles with a single variable, or for the user to selectively use it. + +|Variable Name|Default Value|Required|Description| +|`ah_configuration_user_secure_logging`|`False`|no|Whether or not to include the sensitive Namespace role tasks in the log. Set this value to `True` if you will be providing your sensitive values from elsewhere.| +|`aap_configuration_secure_logging`|`False`|no|This variable enables secure logging as well, but is shared across multiple roles, see above.| + +### Asynchronous Retry Variables + +The following Variables set asynchronous retries for the role. +If neither of the retries or delay or retries are set, they will default to their respective defaults. +This allows for all items to be created, then checked that the task finishes successfully. +This also speeds up the overall role. + +|Variable Name|Default Value|Required|Description| +|`aap_configuration_async_timeout`|1000|no|This variable sets the async timeout for the role globally.| +|`ah_configuration_user_async_timeout`|`aap_configuration_async_timeout`|no|This variable sets the async timeout for the role.| +|`aap_configuration_async_retries`|50|no|This variable sets the number of retries to attempt for the role globally.| +|`ah_configuration_user_async_retries`|`aap_configuration_async_retries`|no|This variable sets the number of retries to attempt for the role.| +|`aap_configuration_loop_delay`|1000|no|This variable sets the loop_delay for the role globally.| +|`ah_configuration_user_accounts_loop_delay`|`aap_configuration_loop_delay`|no|This variable sets the loop_delay for the role.| +|`aap_configuration_async_delay`|1|no|This sets the delay between retries for the role globally.| +|`ah_configuration_user_async_delay`|`aap_configuration_async_delay`|no|This sets the delay between retries for the role.| + +## Data Structure + +### User Variables + +|Variable Name|Default Value|Required|Type|Description| +|`username`|""|yes|str|Username. Must be lower case containing only alphanumeric characters and underscores.| +|`groups`|[]|no|list|List of the groups to update.| +|`append`|true|no|str|Whether to append or replace the group list provided.| +|`first_name`|""|no|str|User's first name.| +|`last_name`|""|no|str|User's last name.| +|`email`|""|no|str|User's email address.| +|`is_superuser`|false|no|bool|Whether the user is a superuser.| +|`password`|""|no|str|User's password as a clear string. The password must contain at least 9 characters with numbers or special characters.| +|`state`|`present`|no|str|Desired state of the user.| + + +### Standard Project Data Structure + +#### Yaml Example + +```yaml +aap_user_accounts: + - username: user1 + groups: + - group1 + append: true + first_name: user + last_name: one + email: user1@example.com + is_superuser: false + password: p4ssword + state: present +``` + +## Playbook Examples + +### Standard Role Usage + +```yaml +- name: Add user to Automation Hub + hosts: localhost + connection: local + gather_facts: false + vars: + aap_validate_certs: false + # Define following vars here, or in ah_configs/ah_auth.yml + # ah_host: ansible-ah-web-svc-test-project.example.com + pre_tasks: + - name: Include vars from ah_configs directory + ansible.builtin.include_vars: + dir: ./vars + extensions: ["yml"] + tags: + - always + roles: + - ../../user +``` + +## License + +[GPLv3+](https://github.com/ansible/galaxy_collection#licensing) + +## Author + +[Tom Page](https://github.com/Tompage1994/) diff --git a/collections/controller_configuration/index.md b/collections/controller_configuration/index.md new file mode 100644 index 0000000..418c290 --- /dev/null +++ b/collections/controller_configuration/index.md @@ -0,0 +1,8 @@ +--- +layout: default +title: infra.controller_configuration +has_children: true +nav_order: 2 +--- + +# controller_configuration \ No newline at end of file diff --git a/collections/controller_configuration/meta_dependency_check.md b/collections/controller_configuration/meta_dependency_check.md new file mode 100644 index 0000000..b8c71e7 --- /dev/null +++ b/collections/controller_configuration/meta_dependency_check.md @@ -0,0 +1,17 @@ +--- +layout: default +title: meta_dependency_check +parent: infra.controller_configuration +--- + +# infra.aap_configuration.meta_dependency_check + +This role is designed to be run before any roles in this collection to check that the underlying awx.awx or ansible.controller collection is installed. This is a dependency of together roles and does not need to be explicitly called. + +## License + +[GPL-3.0](https://github.com/redhat-cop/aap_configuration#licensing) + +## Author + +[Tom Page](https://github.com/Tompage1994) diff --git a/collections/eda_configuration/credential.md b/collections/eda_configuration/credential.md new file mode 100644 index 0000000..39c884c --- /dev/null +++ b/collections/eda_configuration/credential.md @@ -0,0 +1,105 @@ +--- +layout: default +title: credential +parent: infra.eda_configuration +--- + +# infra.eda_configuration.credential + +## Description + +An Ansible Role to create Credentials in EDA Controller. + +## Variables + +|Variable Name|Default Value|Required|Description|Example| +|`eda_host`|""|yes|URL to the EDA Controller (alias: `eda_hostname`)|127.0.0.1| +|`eda_username`|""|yes|Admin User on the EDA Controller || +|`eda_password`|""|yes|EDA Controller Admin User's password on the EDA Controller Server. This should be stored in an Ansible Vault at vars/tower-secrets.yml or elsewhere and called from a parent playbook.|| +|`eda_validate_certs`|`False`|no|Whether or not to validate the Ansible EDA Controller Server's SSL certificate.|| +|`eda_request_timeout`|`10`|no|Specify the timeout Ansible should use in requests to the EDA Controller host.|| +|`eda_configuration_async_dir`|`null`|no|Sets the directory to write the results file for async tasks. The default value is set to `null` which uses the Ansible Default of `/root/.ansible_async/`.|| +|`eda_credentials`|`see below`|yes|Data structure describing your credentials, described below.|| + +### Secure Logging Variables + +The following Variables complement each other. +If Both variables are not set, secure logging defaults to false. +The role defaults to False as normally the add credential task does not include sensitive information. +eda_configuration_credential_secure_logging defaults to the value of eda_configuration_secure_logging if it is not explicitly called. This allows for secure logging to be toggled for the entire suite of EDA Controller configuration roles with a single variable, or for the user to selectively use it. + +|Variable Name|Default Value|Required|Description| +|`eda_configuration_credential_secure_logging`|`True`|no|Whether or not to include the sensitive credential role tasks in the log. Set this value to `True` if you will be providing your sensitive values from elsewhere.| +|`eda_configuration_secure_logging`|`False`|no|This variable enables secure logging as well, but is shared across multiple roles, see above.| + +### Asynchronous Retry Variables + +The following Variables set asynchronous retries for the role. +If neither of the retries or delay or retries are set, they will default to their respective defaults. +This allows for all items to be created, then checked that the task finishes successfully. +This also speeds up the overall role. + +|Variable Name|Default Value|Required|Description| +|`eda_configuration_async_retries`|50|no|This variable sets the number of retries to attempt for the role globally.| +|`eda_configuration_credential_async_retries`|`eda_configuration_async_retries`|no|This variable sets the number of retries to attempt for the role.| +|`eda_configuration_async_delay`|1|no|This sets the delay between retries for the role globally.| +|`eda_configuration_credential_async_delay`|`eda_configuration_async_delay`|no|This sets the delay between retries for the role.| + +## Data Structure + +### Credential Variables + +|Variable Name|Default Value|Required|Type|Description| +|`name`|""|yes|str|Credential name. Must be lower case containing only alphanumeric characters and underscores.| +|`new_name`|""|no|str|Setting this option will change the existing name (looked up via the name field.)| +|`description`|""|no|str|Description to use for the credential.| +|`username`|""|yes|str|The username of the credential.| +|`secret`|""|yes|str|The token or password for the given username (depending upon the credential type).| +|`credential_type`|"GitHub Personal Access Token"|yes|str|The type of the credential.| +|`state`|`present`|no|str|Desired state of the credential.| + +### Standard Credential Data Structure + +#### Yaml Example + +```yaml +eda_credentials: + - name: my_github_user + description: my GitHub Credential + credential_type: 'GitHub Personal Access Token' + username: githubuser + secret: GITHUBTOKEN +``` + +## Playbook Examples + +### Standard Role Usage + +```yaml +- name: Add credential to EDA Controller + hosts: localhost + connection: local + gather_facts: false + vars: + eda_validate_certs: false + # Define following vars here, or in eda_configs/eda_auth.yml + # eda_host: ansible-eda-web-svc-test-credential.example.com + # eda_token: changeme + pre_tasks: + - name: Include vars from eda_configs directory + ansible.builtin.include_vars: + dir: ./vars + extensions: ["yml"] + tags: + - always + roles: + - ../../credential +``` + +## License + +[GPLv3+](https://github.com/redhat-cop/eda_configuration#licensing) + +## Author + +[Derek Waters](https://github.com/derekwaters/) diff --git a/collections/eda_configuration/decision_environment.md b/collections/eda_configuration/decision_environment.md new file mode 100644 index 0000000..6f483d7 --- /dev/null +++ b/collections/eda_configuration/decision_environment.md @@ -0,0 +1,103 @@ +--- +layout: default +title: decision_environment +parent: infra.eda_configuration +--- + +# infra.eda_configuration.decision_environment + +## Description + +An Ansible Role to create Decision Environments in EDA Controller. + +## Variables + +|Variable Name|Default Value|Required|Description|Example| +|`eda_host`|""|yes|URL to the EDA Controller (alias: `eda_hostname`)|127.0.0.1| +|`eda_username`|""|yes|Admin User on the EDA Controller || +|`eda_password`|""|yes|EDA Controller Admin User's password on the EDA Controller Server. This should be stored in an Ansible Vault at vars/tower-secrets.yml or elsewhere and called from a parent playbook.|| +|`eda_validate_certs`|`False`|no|Whether or not to validate the Ansible EDA Controller Server's SSL certificate.|| +|`eda_request_timeout`|`10`|no|Specify the timeout Ansible should use in requests to the EDA Controller host.|| +|`eda_configuration_async_dir`|`null`|no|Sets the directory to write the results file for async tasks. The default value is set to `null` which uses the Ansible Default of `/root/.ansible_async/`.|| +|`eda_decision_environments`|`see below`|yes|Data structure describing your decision environments, described below.|| + +### Secure Logging Variables + +The following Variables complement each other. +If Both variables are not set, secure logging defaults to false. +The role defaults to False as normally the add project task does not include sensitive information. +eda_configuration_project_secure_logging defaults to the value of eda_configuration_secure_logging if it is not explicitly called. This allows for secure logging to be toggled for the entire suite of EDA Controller configuration roles with a single variable, or for the user to selectively use it. + +|Variable Name|Default Value|Required|Description| +|`eda_configuration_project_secure_logging`|`False`|no|Whether or not to include the sensitive Project role tasks in the log. Set this value to `True` if you will be providing your sensitive values from elsewhere.| +|`eda_configuration_secure_logging`|`False`|no|This variable enables secure logging as well, but is shared across multiple roles, see above.| + +### Asynchronous Retry Variables + +The following Variables set asynchronous retries for the role. +If neither of the retries or delay or retries are set, they will default to their respective defaults. +This allows for all items to be created, then checked that the task finishes successfully. +This also speeds up the overall role. + +|Variable Name|Default Value|Required|Description| +|`eda_configuration_async_retries`|50|no|This variable sets the number of retries to attempt for the role globally.| +|`eda_configuration_project_async_retries`|`eda_configuration_async_retries`|no|This variable sets the number of retries to attempt for the role.| +|`eda_configuration_async_delay`|1|no|This sets the delay between retries for the role globally.| +|`eda_configuration_project_async_delay`|`eda_configuration_async_delay`|no|This sets the delay between retries for the role.| + +## Data Structure + +### Decision Environment Variables + +|Variable Name|Default Value|Required|Type|Description| +|`name`|""|yes|str|Decision Environment name. Must be lower case containing only alphanumeric characters and underscores.| +|`new_name`|""|no|str|Setting this option will change the existing name (looked up via the name field.)| +|`description`|""|no|str|Description to use for the Project.| +|`image_url`|""|yes|str|A URL to a a container image to use for the decision environment.| +|`credential`|""|no|str|The credential used to access the container registry holding the image.| +|`state`|`present`|no|str|Desired state of the decision environment.| + +### Standard Decision Environment Data Structure + +#### Yaml Example + +```yaml +eda_decision_environments: + - name: my_default_de + description: my default decision environment + image_url: "image_registry.example.com/default-de:latest" + credential: my_credential +``` + +## Playbook Examples + +### Standard Role Usage + +```yaml +- name: Add decision environment to EDA Controller + hosts: localhost + connection: local + gather_facts: false + vars: + eda_validate_certs: false + # Define following vars here, or in eda_configs/eda_auth.yml + # eda_host: ansible-eda-web-svc-test-project.example.com + # eda_token: changeme + pre_tasks: + - name: Include vars from eda_configs directory + ansible.builtin.include_vars: + dir: ./vars + extensions: ["yml"] + tags: + - always + roles: + - ../../decision_environment +``` + +## License + +[GPLv3+](https://github.com/redhat-cop/eda_configuration#licensing) + +## Author + +[Derek Waters](https://github.com/derekwaters/) diff --git a/collections/eda_configuration/dispatch.md b/collections/eda_configuration/dispatch.md new file mode 100644 index 0000000..565531c --- /dev/null +++ b/collections/eda_configuration/dispatch.md @@ -0,0 +1,92 @@ +--- +layout: default +title: dispatch +parent: infra.eda_configuration +--- + +# infra.eda_configuration.dispatch + +## Description + +An Ansible Role to run all roles on EDA Controller. + +## Requirements + +None + +## Variables + +Each role has its own variables, for information on those please see each role which this role will call. This role has one key variable `eda_configuration_dispatcher_roles` and its default value is shown below: + +```yaml +eda_configuration_dispatcher_roles: + - {role: user, var: eda_users, tags: user} + - {role: credential, var: eda_credentials, tags: credential} + - {role: user_token, var: eda_user_tokens, tags: user_token} + - {role: project, var: eda_projects, tags: project} + - {role: project_sync, var: eda_projects, tags: project_sync} + - {role: decision_environment, var: eda_decision_environments, tags: decision_environment} + - {role: rulebook_activation, var: eda_rulebook_activations, tags: rulebook_activation} +``` + +Note that each item has three elements: + +- `role` which is the name of the role within infra.eda_configuration +- `var` which is the variable which is used in that role. We use this to prevent the role being called if the variable is not set +- `tags` the tags which are applied to the role so it is possible to apply tags to a playbook using the dispatcher with these tags. + +It is possible to redefine this variable with a subset of roles or with different tags. In general we suggest keeping the same structure and perhaps just using a subset. + +### Authentication + +|Variable Name|Default Value|Required|Description|Example| +|`eda_state`|"present"|no|The state all objects will take unless overridden by object default|'absent'| +|`eda_hostname`|""|yes|URL to the EDA Server.|127.0.0.1| +|`eda_validate_certs`|`True`|no|Whether or not to validate the EDA Controller Server's SSL certificate.|| +|`eda_username`|""|no|Admin User on the EDA Controller Server.|| +|`eda_password`|""|no|EDA Admin User's password on the EDA Controller Server. This should be stored in an Ansible Vault at vars/eda-secrets.yml or elsewhere and called from a parent playbook.|| + +### Secure Logging Variables + +The role defaults to False as normally most projects task does not include sensitive information. +Each role the dispatch role calls has a separate variable which can be turned on to enforce secure logging for that role but defaults to the value of eda_configuration_secure_logging if it is not explicitly called. This allows for secure logging to be toggled for the entire suite of configuration roles with a single variable, or for the user to selectively use it. If neither value is set then each role has a default value of true or false depending on the Red Hat COP suggestions. + +|Variable Name|Default Value|Required|Description| +|`eda_configuration_secure_logging`|""|no|This variable enables secure logging as well, but is shared across multiple roles, see above.| + +### Asynchronous Retry Variables + +The following Variables set asynchronous retries for the role. +If neither of the retries or delay or retries are set, they will default to their respective defaults. +This allows for all items to be created, then checked that the task finishes successfully. +This also speeds up the overall role. Each individual role has its own variable which can allow the individual setting of values. See each role for more the variable names. + +|Variable Name|Default Value|Required|Description| +|`eda_configuration_async_retries`|30|no|This variable sets the number of retries to attempt for the role globally.| +|`eda_configuration_async_delay`|1|no|This sets the delay between retries for the role globally.| + +## Playbook Examples + +### Standard Role Usage + +```yaml +- name: Playbook to configure EDA post installation + hosts: localhost + connection: local + pre_tasks: + - name: Include vars from eda_configs directory + ansible.builtin.include_vars: + dir: ./yaml + ignore_files: [eda_config.yml.template] + extensions: ["yml"] + roles: + - infra.eda_configuration.dispatch +``` + +## License + +[GPL-3.0](https://github.com/redhat-cop/eda_configuration#licensing) + +## Author + +[Tom Page](https://github.com/Tompage1994) diff --git a/collections/eda_configuration/index.md b/collections/eda_configuration/index.md new file mode 100644 index 0000000..81906c6 --- /dev/null +++ b/collections/eda_configuration/index.md @@ -0,0 +1,8 @@ +--- +layout: default +title: infra.eda_configuration +has_children: true +nav_order: 4 +--- + +# eda_configuration \ No newline at end of file diff --git a/collections/eda_configuration/project.md b/collections/eda_configuration/project.md new file mode 100644 index 0000000..ae3c2f8 --- /dev/null +++ b/collections/eda_configuration/project.md @@ -0,0 +1,105 @@ +--- +layout: default +title: project +parent: infra.eda_configuration +--- + +# infra.eda_configuration.project + +## Description + +An Ansible Role to create Projects in EDA Controller. + +## Variables + +|Variable Name|Default Value|Required|Description|Example| +|`eda_host`|""|yes|URL to the EDA Controller (alias: `eda_hostname`)|127.0.0.1| +|`eda_username`|""|yes|Admin User on the EDA Controller || +|`eda_password`|""|yes|EDA Controller Admin User's password on the EDA Controller Server. This should be stored in an Ansible Vault at vars/tower-secrets.yml or elsewhere and called from a parent playbook.|| +|`eda_validate_certs`|`False`|no|Whether or not to validate the Ansible EDA Controller Server's SSL certificate.|| +|`eda_request_timeout`|`10`|no|Specify the timeout Ansible should use in requests to the EDA Controller host.|| +|`eda_configuration_async_dir`|`null`|no|Sets the directory to write the results file for async tasks. The default value is set to `null` which uses the Ansible Default of `/root/.ansible_async/`.|| +|`eda_projects`|`see below`|yes|Data structure describing your projects, described below.|| + +### Secure Logging Variables + +The following Variables compliment each other. +If Both variables are not set, secure logging defaults to false. +The role defaults to False as normally the add project task does not include sensitive information. +eda_configuration_project_secure_logging defaults to the value of eda_configuration_secure_logging if it is not explicitly called. This allows for secure logging to be toggled for the entire suite of EDA Controller configuration roles with a single variable, or for the user to selectively use it. + +|Variable Name|Default Value|Required|Description| +|`eda_configuration_project_secure_logging`|`False`|no|Whether or not to include the sensitive Project role tasks in the log. Set this value to `True` if you will be providing your sensitive values from elsewhere.| +|`eda_configuration_secure_logging`|`False`|no|This variable enables secure logging as well, but is shared across multiple roles, see above.| + +### Asynchronous Retry Variables + +The following Variables set asynchronous retries for the role. +If neither of the retries or delay or retries are set, they will default to their respective defaults. +This allows for all items to be created, then checked that the task finishes successfully. +This also speeds up the overall role. + +|Variable Name|Default Value|Required|Description| +|`eda_configuration_async_retries`|50|no|This variable sets the number of retries to attempt for the role globally.| +|`eda_configuration_project_async_retries`|`eda_configuration_async_retries`|no|This variable sets the number of retries to attempt for the role.| +|`eda_configuration_async_delay`|1|no|This sets the delay between retries for the role globally.| +|`eda_configuration_project_async_delay`|`eda_configuration_async_delay`|no|This sets the delay between retries for the role.| + +## Data Structure + +### Project Variables + +|Variable Name|Default Value|Required|Type|Description| +|`name`|""|yes|str|Project name. Must be lower case containing only alphanumeric characters and underscores.| +|`new_name`|""|no|str|Setting this option will change the existing name (looked up via the name field.)| +|`description`|""|no|str|Description to use for the Project.| +|`url`|""|yes|str|A URL to a remote archive, such as a Github Release or a build artifact stored in Artifactory and unpacks it into the project path for use. (Alias: scm_url)| +|`tls_validation`|true|no|bool|Whether the URL should validate using TLS.| +|`credential`|""|no|str|The token needed to utilize the SCM URL.| +|`state`|`present`|no|str|Desired state of the project.| + +### Standard Project Data Structure + +#### Yaml Example + +```yaml +eda_projects: + - name: my_project + description: my awesome project + url: https://github.com/ansible/ansible-rulebook.git + tls_validation: true + credential: test_token +``` + +## Playbook Examples + +### Standard Role Usage + +```yaml +- name: Add project to EDA Controller + hosts: localhost + connection: local + gather_facts: false + vars: + eda_validate_certs: false + # Define following vars here, or in eda_configs/eda_auth.yml + # eda_host: ansible-eda-web-svc-test-project.example.com + # eda_token: changeme + pre_tasks: + - name: Include vars from eda_configs directory + ansible.builtin.include_vars: + dir: ./vars + extensions: ["yml"] + tags: + - always + roles: + - ../../project +``` + +## License + +[GPLv3+](https://github.com/redhat-cop/eda_configuration#licensing) + +## Author + +[Chris Renwick](https://github.com/crenwick93/) diff --git a/collections/eda_configuration/project_sync.md b/collections/eda_configuration/project_sync.md new file mode 100644 index 0000000..e163686 --- /dev/null +++ b/collections/eda_configuration/project_sync.md @@ -0,0 +1,105 @@ +--- +layout: default +title: project_sync +parent: infra.eda_configuration +--- + +# infra.eda_configuration.project + +## Description + +An Ansible Role to create Projects in EDA Controller. + +## Variables + +|Variable Name|Default Value|Required|Description|Example| +|`eda_host`|""|yes|URL to the EDA Controller (alias: `eda_hostname`)|127.0.0.1| +|`eda_username`|""|yes|Admin User on the EDA Controller || +|`eda_password`|""|yes|EDA Controller Admin User's password on the EDA Controller Server. This should be stored in an Ansible Vault at vars/tower-secrets.yml or elsewhere and called from a parent playbook.|| +|`eda_validate_certs`|`False`|no|Whether or not to validate the Ansible EDA Controller Server's SSL certificate.|| +|`eda_request_timeout`|`10`|no|Specify the timeout Ansible should use in requests to the EDA Controller host.|| +|`eda_configuration_async_dir`|`null`|no|Sets the directory to write the results file for async tasks. The default value is set to `null` which uses the Ansible Default of `/root/.ansible_async/`.|| +|`eda_projects`|`see below`|yes|Data structure describing your projects, described below. Note that this role will only do anything if the `sync` suboption of this variable is set to true.|| + +### Secure Logging Variables + +The following Variables compliment each other. +If Both variables are not set, secure logging defaults to false. +The role defaults to False as normally the add project task does not include sensitive information. +eda_configuration_project_secure_logging defaults to the value of eda_configuration_secure_logging if it is not explicitly called. This allows for secure logging to be toggled for the entire suite of EDA Controller configuration roles with a single variable, or for the user to selectively use it. + +|Variable Name|Default Value|Required|Description| +|`eda_configuration_project_secure_logging`|`False`|no|Whether or not to include the sensitive Project role tasks in the log. Set this value to `True` if you will be providing your sensitive values from elsewhere.| +|`eda_configuration_secure_logging`|`False`|no|This variable enables secure logging as well, but is shared across multiple roles, see above.| + +### Asynchronous Retry Variables + +The following Variables set asynchronous retries for the role. +If neither of the retries or delay or retries are set, they will default to their respective defaults. +This allows for all items to be created, then checked that the task finishes successfully. +This also speeds up the overall role. + +|Variable Name|Default Value|Required|Description| +|`eda_configuration_async_retries`|50|no|This variable sets the number of retries to attempt for the role globally.| +|`eda_configuration_project_sync_async_retries`|`eda_configuration_async_retries`|no|This variable sets the number of retries to attempt for the role.| +|`eda_configuration_async_delay`|1|no|This sets the delay between retries for the role globally.| +|`eda_configuration_project_sync_async_delay`|`eda_configuration_async_delay`|no|This sets the delay between retries for the role.| + +## Data Structure + +### Project Variables + +|Variable Name|Default Value|Required|Type|Description| +|`name`|""|yes|str|Project name. Must be lower case containing only alphanumeric characters and underscores.| +|`sync`|false|no|bool|Whether to sync the project. By default it will not sync unless this is set to true.| +|`wait`|true|no|str|Whether to wait for the sync to complete| +|`interval`|`eda_configuration_project_sync_async_delay`|no|str|The interval which the sync task will be checked for completion| +|`timeout`|""|no|str|How long to wait for the sync task to complete| + +### Standard Project Data Structure + +#### Yaml Example + +```yaml +eda_projects: + - name: my_project + description: my awesome project + url: https://github.com/ansible/ansible-rulebook.git + credential: test_token + wait: true + interval: 10 + sync: true +``` + +## Playbook Examples + +### Standard Role Usage + +```yaml +- name: Sync project to EDA Controller + hosts: localhost + connection: local + gather_facts: false + vars: + eda_validate_certs: false + # Define following vars here, or in eda_configs/eda_auth.yml + # eda_host: ansible-eda-web-svc-test-project.example.com + # eda_token: changeme + pre_tasks: + - name: Include vars from eda_configs directory + ansible.builtin.include_vars: + dir: ./vars + extensions: ["yml"] + tags: + - always + roles: + - ../../project_sync +``` + +## License + +[GPLv3+](https://github.com/redhat-cop/eda_configuration#licensing) + +## Author + +[Tom Page](https://github.com/Tompage1994/) diff --git a/collections/eda_configuration/rulebook_activation.md b/collections/eda_configuration/rulebook_activation.md new file mode 100644 index 0000000..312aee3 --- /dev/null +++ b/collections/eda_configuration/rulebook_activation.md @@ -0,0 +1,113 @@ +--- +layout: default +title: rulebook_activation +parent: infra.eda_configuration +--- + +# infra.eda_configuration.rulebook_activation + +## Description + +An Ansible Role to create rulebook activations in EDA Controller. + +## Variables + +|Variable Name|Default Value|Required|Description|Example| +|`eda_host`|""|yes|URL to the EDA Controller (alias: `eda_hostname`)|127.0.0.1| +|`eda_username`|""|yes|Admin User on the EDA Controller || +|`eda_password`|""|yes|EDA Controller Admin User's password on the EDA Controller Server. This should be stored in an Ansible Vault at vars/tower-secrets.yml or elsewhere and called from a parent playbook.|| +|`eda_validate_certs`|`False`|no|Whether or not to validate the Ansible EDA Controller Server's SSL certificate.|| +|`eda_request_timeout`|`10`|no|Specify the timeout Ansible should use in requests to the EDA Controller host.|| +|`eda_configuration_async_dir`|`null`|no|Sets the directory to write the results file for async tasks. The default value is set to `null` which uses the Ansible Default of `/root/.ansible_async/`.|| +|`eda_rulebook_activations`|`see below`|yes|Data structure describing your rulebook activations, described below.|| + +### Secure Logging Variables + +The following Variables complement each other. +If Both variables are not set, secure logging defaults to false. +The role defaults to False as normally the add project task does not include sensitive information. +eda_configuration_project_secure_logging defaults to the value of eda_configuration_secure_logging if it is not explicitly called. This allows for secure logging to be toggled for the entire suite of EDA Controller configuration roles with a single variable, or for the user to selectively use it. + +|Variable Name|Default Value|Required|Description| +|`eda_configuration_project_secure_logging`|`False`|no|Whether or not to include the sensitive Project role tasks in the log. Set this value to `True` if you will be providing your sensitive values from elsewhere.| +|`eda_configuration_secure_logging`|`False`|no|This variable enables secure logging as well, but is shared across multiple roles, see above.| + +### Asynchronous Retry Variables + +The following Variables set asynchronous retries for the role. +If neither of the retries or delay or retries are set, they will default to their respective defaults. +This allows for all items to be created, then checked that the task finishes successfully. +This also speeds up the overall role. + +|Variable Name|Default Value|Required|Description| +|`eda_configuration_async_retries`|50|no|This variable sets the number of retries to attempt for the role globally.| +|`eda_configuration_project_async_retries`|`eda_configuration_async_retries`|no|This variable sets the number of retries to attempt for the role.| +|`eda_configuration_async_delay`|1|no|This sets the delay between retries for the role globally.| +|`eda_configuration_project_async_delay`|`eda_configuration_async_delay`|no|This sets the delay between retries for the role.| + +## Data Structure + +### Rulebook activation Variables + +|Variable Name|Default Value|Required|Type|Description| +|`name`|""|yes|str|Rulebook activation name. Must be lower case containing only alphanumeric characters and underscores.| +|`description`|""|no|str|Description to use for the Activation.| +|`project`|""|no|str|Project to use for the Activation.| +|`rulebook`|""|yes|str|rulebook to use for the Activation.| +|`decision_environment`|""|yes|str|Decision_environment to use for the Activation.| +|`restart_policy`|"always"|no|str|Restart_policy to use for the Activation, choice of ["always", "never", "on-failure"]| +|`extra_vars`|""|no|str|Extra_vars to use for the Activation.| +|`awx_token`|""|no|str|The token used to authenticate to controller.| +|`enabled`|"true"|no|str|Whether the rulebook activation is automatically enabled to run.| +|`state`|`present`|no|str|Desired state of the rulebook activation.| + +### Standard rulebook activation Data Structure + +#### Yaml Example + +```yaml +eda_rulebook_activations: + - name: Github Hook + description: Hook to listen for changes in GitHub + project: EDA_example + rulebook: git-hook-deploy-rules.yml + decision_environment: Automation Hub Default Decision Environment + extra_vars: + provider: github-local + repo_url: https://github.com/ansible/ansible-rulebook.git + enabled: false + state: present +``` + +## Playbook Examples + +### Standard Role Usage + +```yaml +- name: Add rulebook activation to EDA Controller + hosts: localhost + connection: local + gather_facts: false + vars: + eda_validate_certs: false + # Define following vars here, or in eda_configs/eda_auth.yml + # eda_host: ansible-eda-web-svc-test-project.example.com + # eda_token: changeme + pre_tasks: + - name: Include vars from eda_configs directory + ansible.builtin.include_vars: + dir: ./vars + extensions: ["yml"] + tags: + - always + roles: + - ../../rulebook_activation +``` + +## License + +[GPLv3+](https://github.com/redhat-cop/eda_configuration#licensing) + +## Author + +[Tom Page](https://github.com/Tompage1994/) diff --git a/collections/eda_configuration/user.md b/collections/eda_configuration/user.md new file mode 100644 index 0000000..a32ccc0 --- /dev/null +++ b/collections/eda_configuration/user.md @@ -0,0 +1,111 @@ +--- +layout: default +title: user +parent: infra.eda_configuration +--- + +# infra.eda_configuration.user + +## Description + +An Ansible Role to create users in EDA Controller. + +## Variables + +|Variable Name|Default Value|Required|Description|Example| +|`eda_host`|""|yes|URL to the EDA Controller (alias: `eda_hostname`)|127.0.0.1| +|`eda_username`|""|yes|Admin User on the EDA Controller || +|`eda_password`|""|yes|EDA Controller Admin User's password on the EDA Controller Server. This should be stored in an Ansible Vault at vars/tower-secrets.yml or elsewhere and called from a parent playbook.|| +|`eda_validate_certs`|`False`|no|Whether or not to validate the Ansible EDA Controller Server's SSL certificate.|| +|`eda_request_timeout`|`10`|no|Specify the timeout Ansible should use in requests to the EDA Controller host.|| +|`eda_configuration_async_dir`|`null`|no|Sets the directory to write the results file for async tasks. The default value is set to `null` which uses the Ansible Default of `/root/.ansible_async/`.|| +|`eda_users`|`see below`|yes|Data structure describing your users, described below.|| + +### Secure Logging Variables + +The following Variables compliment each other. +If Both variables are not set, secure logging defaults to false. +The role defaults to False as normally the add user task does not include sensitive information. +eda_configuration_user_secure_logging defaults to the value of eda_configuration_secure_logging if it is not explicitly called. This allows for secure logging to be toggled for the entire suite of EDA Controller configuration roles with a single variable, or for the user to selectively use it. + +|Variable Name|Default Value|Required|Description| +|`eda_configuration_user_secure_logging`|`False`|no|Whether or not to include the sensitive user role tasks in the log. Set this value to `True` if you will be providing your sensitive values from elsewhere.| +|`eda_configuration_secure_logging`|`False`|no|This variable enables secure logging as well, but is shared across multiple roles, see above.| + +### Asynchronous Retry Variables + +The following Variables set asynchronous retries for the role. +If neither of the retries or delay or retries are set, they will default to their respective defaults. +This allows for all items to be created, then checked that the task finishes successfully. +This also speeds up the overall role. + +|Variable Name|Default Value|Required|Description| +|`eda_configuration_async_retries`|50|no|This variable sets the number of retries to attempt for the role globally.| +|`eda_configuration_user_async_retries`|`eda_configuration_async_retries`|no|This variable sets the number of retries to attempt for the role.| +|`eda_configuration_async_delay`|1|no|This sets the delay between retries for the role globally.| +|`eda_configuration_user_async_delay`|`eda_configuration_async_delay`|no|This sets the delay between retries for the role.| + +## Data Structure + +### user Variables + +|Variable Name|Default Value|Required|Type|Description| +|`username`|""|yes|str|Username. Must contain only letters, numbers, and `@.+-_` characters.| +|`new_username`|""|no|str|Setting this option will change the existing username (looked up via the name field.)| +|`first_name`|""|no|str|First ame of the user.| +|`last_name`|""|no|str|Last name of the user.| +|`email`|""|no|str|User's email address.| +|`password`|""|yes|str|Password to use for the user.| +|`update_secrets`|true|no|bool|Setting true will always change password if user specifies password. Password will only change if false if other fields change.| +|`roles`|""|yes|list|Roles the user will have. Current acceptable values are: Viewer, Auditor, Editor, Contributor, Operator, Admin.| +|`state`|`present`|no|str|Desired state of the user.| + +### Standard user Data Structure + +#### Yaml Example + +```yaml +eda_users: +- username: jane_doe + first_name: Jane + last_name: Doe + email: jdoe@example.com + password: my_password1 + update_secrets: false + roles: + - Auditor + - Contributor +``` + +## Playbook Examples + +### Standard Role Usage + +```yaml +- name: Add user to EDA Controller + hosts: localhost + connection: local + gather_facts: false + vars: + eda_validate_certs: false + # Define following vars here, or in eda_configs/eda_auth.yml + # eda_host: ansible-eda-web-svc-test-user.example.com + # eda_token: changeme + pre_tasks: + - name: Include vars from eda_configs directory + ansible.builtin.include_vars: + dir: ./vars + extensions: ["yml"] + tags: + - always + roles: + - ../../user +``` + +## License + +[GPLv3+](https://github.com/redhat-cop/eda_configuration#licensing) + +## Author + +[Tom Page](https://github.com/Tompage1994/) diff --git a/collections/eda_configuration/user_token.md b/collections/eda_configuration/user_token.md new file mode 100644 index 0000000..af4d0c3 --- /dev/null +++ b/collections/eda_configuration/user_token.md @@ -0,0 +1,101 @@ +--- +layout: default +title: user_token +parent: infra.eda_configuration +--- + +# infra.eda_configuration.user_token + +## Description + +An Ansible Role to create User Tokens in EDA Controller. Note that tokens may only be applied to the user account accessing the API (ie. eda_username) +Note that tokens cannot be updated, only created. + +## Variables + +|Variable Name|Default Value|Required|Description|Example| +|`eda_host`|""|yes|URL to the EDA Controller (alias: `eda_hostname`)|127.0.0.1| +|`eda_username`|""|yes|Admin User on the EDA Controller || +|`eda_password`|""|yes|EDA Controller Admin User's password on the EDA Controller Server. This should be stored in an Ansible Vault at vars/tower-secrets.yml or elsewhere and called from a parent playbook.|| +|`eda_validate_certs`|`False`|no|Whether or not to validate the Ansible EDA Controller Server's SSL certificate.|| +|`eda_request_timeout`|`10`|no|Specify the timeout Ansible should use in requests to the EDA Controller host.|| +|`eda_configuration_async_dir`|`null`|no|Sets the directory to write the results file for async tasks. The default value is set to `null` which uses the Ansible Default of `/root/.ansible_async/`.|| +|`eda_user_tokens`|`see below`|yes|Data structure describing your user tokens, described below.|| + +### Secure Logging Variables + +The following Variables complement each other. +If Both variables are not set, secure logging defaults to false. +The role defaults to False as normally the add project task does not include sensitive information. +eda_configuration_user_token_secure_logging defaults to the value of eda_configuration_secure_logging if it is not explicitly called. This allows for secure logging to be toggled for the entire suite of EDA Controller configuration roles with a single variable, or for the user to selectively use it. + +|Variable Name|Default Value|Required|Description| +|`eda_configuration_user_token_secure_logging`|`False`|no|Whether or not to include the sensitive Project role tasks in the log. Set this value to `True` if you will be providing your sensitive values from elsewhere.| +|`eda_configuration_secure_logging`|`False`|no|This variable enables secure logging as well, but is shared across multiple roles, see above.| + +### Asynchronous Retry Variables + +The following Variables set asynchronous retries for the role. +If neither of the retries or delay or retries are set, they will default to their respective defaults. +This allows for all items to be created, then checked that the task finishes successfully. +This also speeds up the overall role. + +|Variable Name|Default Value|Required|Description| +|`eda_configuration_async_retries`|50|no|This variable sets the number of retries to attempt for the role globally.| +|`eda_configuration_user_token_async_retries`|`eda_configuration_async_retries`|no|This variable sets the number of retries to attempt for the role.| +|`eda_configuration_async_delay`|1|no|This sets the delay between retries for the role globally.| +|`eda_configuration_user_token_async_delay`|`eda_configuration_async_delay`|no|This sets the delay between retries for the role.| + +## Data Structure + +### User Token Variables + +|Variable Name|Default Value|Required|Type|Description| +|`name`|""|yes|str|User Token name. Must be lower case containing only alphanumeric characters and underscores.| +|`new_name`|""|no|str|Setting this option will change the existing name (looked up via the name field.)| +|`description`|""|no|str|Description to use for the Project.| +|`token`|""|yes|str|The value of the token to associate with the user.| + +### Standard User Token Data Structure + +#### Yaml Example + +```yaml +eda_user_tokens: + - name: my_default_token + description: my default user token + token: TOKEN_VALUE +``` + +## Playbook Examples + +### Standard Role Usage + +```yaml +- name: Add user token to EDA Controller + hosts: localhost + connection: local + gather_facts: false + vars: + eda_validate_certs: false + # Define following vars here, or in eda_configs/eda_auth.yml + # eda_host: ansible-eda-web-svc-test-project.example.com + # eda_token: changeme + pre_tasks: + - name: Include vars from eda_configs directory + ansible.builtin.include_vars: + dir: ./vars + extensions: ["yml"] + tags: + - always + roles: + - ../../user_token +``` + +## License + +[GPLv3+](https://github.com/redhat-cop/eda_configuration#licensing) + +## Author + +[Derek Waters](https://github.com/derekwaters/) diff --git a/collections/ee_utilities/ee_builder.md b/collections/ee_utilities/ee_builder.md new file mode 100644 index 0000000..41194ac --- /dev/null +++ b/collections/ee_utilities/ee_builder.md @@ -0,0 +1,262 @@ +--- +layout: default +title: ee_builder +parent: infra.ee_utilities +--- + +# infra.ee_utilities.ee_builder + +Ansible role use to build execution environments. This role invokes ansible builder and depends on certain variables or files being provided. + +## Requirements + +ansible-builder +podman or docker + +## Role Variables + +Available variables are listed below, along with default values defined (see defaults/main.yml) + +Order of preferences for images + +1. ee_list images + + ```yaml + ee_list: + - name: custom_ee + base_image: image_name + ``` + +2. 'ee_base_image' top level variables. + +3. If none of the above are set, a default will be used. + + Downstream images from the redhat registery will be used if you provide a 'ee_base_registry_username' + Otherwise it will default to the upstream images on quay. These are only used if no base is specificed. + + ```yaml + upstream: + base_image: quay.io/ansible/ansible-runner:latest + downstream: + base_image: registry.redhat.io/ansible-automation-platform-24/ee-minimal-rhel9:latest + ``` + +Best practice is to use the default images, unless needing to pull from another repository. + +### Build Argument Defaults + +|Variable Name|Default Value|Required|Type|Description|Example| +|`ee_builder_dir`|playbook_directory|no|str|The directory to store all build and context files.|'/tmp'| +|`ee_builder_dir_clean`|true|no|bool|Whether to delete the build dir when done.|true| +|`ee_container_runtime`|podman|no|str|container run time to use podman/docker.|podman| +|`ee_version`|3|no|int|What Execution Environment definition file version to use. This can be different then the actual buider version.|3| +|`ee_galaxy_keyring`||no|str|Path to the keyring to verify collection signatures during installation.|| +|`ee_galaxy_ignore_signature_status_code`||no|list|List of status codes to ignore while verifying collections.|-500| +|`galaxy_required_valid_signature_count`||no|int|Number of required valid collection signatures.|5| +|`ee_container_policy`||no|str|The container image validation policy to use with podman. Can be one of 'ignore_all', 'system','signature_required'.|ignore_all| +|`ee_verbosity`|0|no|int|Options Increase the output verbosity, can be from 0-3.|| +|`ee_prune_images`|true|no|bool|To enable or disable pruning the images after building.|| +|`ee_stream`|upstream unless ee_base_registry_username is defined then downstream|no|str|What stream to pull images from either upstream or downstream. Also changes package manager used for downstream to microdnf to avoid errors.|| +|`ee_update_base_images`|false|no|bool|Whether to pull down images, this forces an update to avoid stale images.|| +|`ee_base_image`|registry.redhat.io/ansible-automation-platform-24/ee-minimal-rhel9:latest|no|str|Build arg specifies parent image for the execution environment. Use the images option to override this for an individual list item.|| +|`ee_base_registry_username`|ee_registry_username|no|str|Username to use when authenticating to base registries. If neither ee or base registry provided will be omitted.|| +|`ee_base_registry_password`|ee_registry_password|no|str|Password to use when authenticating to base registries. If neither ee or base registry provided will be omitted.|| +|`ee_pull_collections_from_hub`|true|no|bool|Whether or not to pull collections from a specific hub for use in building an Execution Environment. This will create entries that adds the ansible.cfg file into the EE.|| +|`ee_ah_host`|`ah_host`|no|str|Host to use for ansible config file. Alternative default is to use variable from infra.ah_configuration. Required if `ee_pull_collections_from_hub` is `True`.|| +|`ee_ah_token`|`ah_token`|no|str|Token to use for ansible config file. Alternative default is to use variable from infra.ah_configuration. Required if `ee_pull_collections_from_hub` is `True`.|| +|`ee_create_controller_def`|false|no|bool|Option to create the 'controller_execution_environments' definition for use by the infra.controller_configuration role|| +### Execution environment list + +This role takes a list of execution environments to describe a state. +It takes variables from the following sections the list variables section. + +|Variable Name|Default Value|Required|Description| +|`ee_list`|`list`|yes|Data structure describing your Execution Environments Described below.| + +#### List variables for Execution environment definition + +|Variable Name|Default Value|Required|Description| +|`name`||yes|Name of the ee image to create. Only the name goes here, the namespace goes in the ee_registry_dest variable| +|`tag`||no|Tag to use when pushing the image.| +|`dependencies`|dict|no|This section allows you to describe any dependencies that will need to be installed into the final image. Reference [builder dependencies documentation](https://ansible.readthedocs.io/projects/builder/en/stable/definition/#dependencies), examples and our examples for its structure.| +|`build_steps`|dict|no|This section enables you to specify custom build commands for any build phase. Reference [builder build_steps documentation](https://ansible.readthedocs.io/projects/builder/en/stable/definition/#additional-build-steps), examples and our examples for its structure.| +|`build_items`|list|no|This is a list of files or folders that will be copied to the working directory for use with the build files. Example below.| +|`build_files`|dict|no|This section allows you to add any file to the build context directory. Reference [builder build_files documentation](https://ansible.readthedocs.io/projects/builder/en/stable/definition/#additional-build-files), examples and our examples for its structure.| +|`images`|dict|no|This section is a dictionary that is used to define the base image to be used. Reference [builder images documentation](https://ansible.readthedocs.io/projects/builder/en/stable/definition/#images), examples and our examples for its structure. This will override 'ee_base_image'.| +|`options`|dict|no|This section is a dictionary that contains keywords/options that can affect builder runtime functionality. Reference [builder options documentation](https://ansible.readthedocs.io/projects/builder/en/stable/definition/#options), examples and our examples for its structure.| +|`skip_generation`|bool|false|Should the generation of execution_environment.yml be skipped and an already provided definition be used.| + +#### Additional List variables for Execution environment definition for Controller configuration + +These variables are only use in creating the Execution Environment 'controller_execution_environments' definition that is useable wtih the infra.controller_configuration role to push definitions to the Automation controller. + +|Variable Name|Default Value|Required|Type|Description| +|`alt_name`|`name`|no|str|Alternate name of the ee image to create.| +|`description`|""|no|str|Description to use for the execution environment.| +|`organization`|""|no|str|The organization the execution environment belongs to.| +|`pull`|"missing"|no|choice("always", "missing", "never")|Determine image pull behavior| +|`ee_reg_credential`|""|no|str|Name of the credential to use for the execution environment.| + +### Registry Step defaults + +|Variable Name|Default Value|Required|Description| +|`ee_registry_username`||no|Username to use when authenticating to destination registries.| +|`ee_registry_password`||no|Password to use when authenticating to destination registries.| +|`ee_registry_dest`||no|Path or URL where image will be pushed. Namespaces for containers go here. Examples: registry.redhat.io, registry.redhat.io/rh-custom | +|`ee_image_push`|True|no|Control to choose whether to push image to registry or not.| +|`ee_auth_file`||no|Path to file containing authorization credentials to the remote registry.| +|`ee_executable`||no|Path to podman executable if it is not in the $PATH on the machine running podman.| +|`ee_ca_cert_dir`||no|Path to directory containing TLS certificates and keys to use.| +|`ee_validate_certs`||no|Require HTTPS and validate certificates when pulling or pushing. | +|`ee_sign_by`||no|Path to a key file to use to sign the image.| + +## Example Playbook + +The following playbook can be invoked in the following manner. This role is meant to build and push an execution Environment to an registry + +```sh +ansible-playbook playbook.yml +``` + +```yaml +- name: Playbook to create custom EE + hosts: localhost + gather_facts: false + collections: + - infra.ee_utilities + vars: + # For controller configuration definition + ee_builder_dir_clean: false + ee_builder_dir: "." + ee_update_base_images: false + ee_reg_credential: Automation Hub Container Registry + ee_base_image: registry.redhat.io/ansible-automation-platform-24/ee-minimal-rhel9:latest + ee_pull_collections_from_hub: true + ah_host: hub.nas + ah_token: ec28091dfebd9fb4c7ddc59d34cddb35350b71cb + ee_registry_dest: ahnosso.node + ee_registry_username: admin + ee_registry_password: secret123 + ee_verbosity: 1 + ee_list: + - name: custom_ee + alt_name: Custom EE + tag: 1-11-21-2 + dependencies: + system: + - python-requests + - python-pyyaml + python: + - pytz # for schedule_rrule lookup plugin + - python-dateutil>=2.7.0 # schedule_rrule + - awxkit # For import and export modules + galaxy: + collections: + - name: awx.awx + version: 22.4.0 + - infra.controller_configuration + - ansible.controller + - infra.ah_configuration + build_items: + - files/ + - test.yml + build_files: + - src: files/stuff.txt + dest: folders + - src: test.yml + dest: folders + build_steps: + prepend_final: + - ADD _build/folders/stuff.txt /etc/ansible/stuff.txt + - ADD _build/folders/test.yml /etc/ansible/test.yml + append_final: + - RUN echo This is a post-install command! + roles: + - infra.ee_utilities.ee_builder +``` + +This is an example for building using automated pipelines like Gitlab or Azure Devops where the build container and other dependencies used for building the final artifact are destroyed after the pipeline is finished + +```yaml +- name: Playbook to create custom EE + hosts: localhost + gather_facts: false + collections: + - infra.ee_utilities + # One of these two may be required in certain environments + # - containers.podman + # - community.docker + vars: + ee_base_registry_username: admin + ee_base_registry_password: secret123 + ee_base_image: registry.redhat.io/ansible-automation-platform-24/ee-minimal-rhel9:latest + # As stated in ee_registry_dest's description, if you want to namespace an image you put the namespace in the ee_registry_dest variable like so instead of in the name variable + ee_registry_dest: ahnosso.node/custom-images-for-prod + ee_registry_username: admin + ee_registry_password: secret123 + # in this example we are assuming that we are pulling content and pushing the final artifact to the same location + ee_ah_host: ahnosso.node + ee_ah_token: iamatoken + # ee_builder_dir_clean is used because depending on the environment permissions errors can be thrown when attempting to clean up. It is also unnecessary if the entire environment is going to be destroyed at the end anyway. + # + ee_builder_dir_clean: false + # ee_builder_dir is set to the relative path "." because it tells ansible-builder to always use the temporary folder created by the pipeline. This may not be necessary depending on the envirnment but the temporary directories created by the pipeline for building the final artifacts can vary in location + ee_builder_dir: "." + ee_list: + # To reiterate, only the name variable goes here, not the namespace, that is placed in ee_registry_dest, please refer to ee_registry_dest's description for more details + - name: custom_ee + # Using the latest tag is best practice and should be replaced with a tested version of the container. However latest can be a good starting point to figure out which container works, then replacing latest with the version number for the tested latest container. + images: + base_image: + name: registry.redhat.io/ansible-automation-platform-24/ee-minimal-rhel9:latest + dependencies: + ansible_core: + package_pip: ansible-core==2.15 + ansible_runner: + package_pip: ansible-runner + system: + - python-requests + - python-pyyaml + python: + - pytz # for schedule_rrule lookup plugin + - python-dateutil>=2.7.0 # schedule_rrule + - awxkit # For import and export modules + galaxy: + collections: + - name: awx.awx + version: 22.4.0 + - infra.controller_configuration + - ansible.controller + - infra.ah_configuration + build_steps: + prepend_final: + - RUN whoami + - RUN cat /etc/os-release + append_final: + - RUN echo This is a post-install command! + # This overwrites the above base image. + - name: custom_suported + alt_name: Custom EE2 + ee_base_image: registry.redhat.io/ansible-automation-platform-24/ee-supported-rhel9:latest + dependencies: + galaxy: + collections: + - community.aws +# This pre-task section is provided because older environment or environments like build pipelines may not have ansible-builder pre-installed. This is a good place to install other dependencies that need to be in the build pipeline its self not in the final artifact. +# pre_tasks: +# - name: install ansible-builder +# ansible.builtin.pip: +# name: ansible-builder +# executable: pip3.9 +# tags: always + roles: + - infra.ee_utilities.ee_builder +``` + +## License + +[GPLv3+](https://github.com/redhat-cop/ee_utilities#licensing) + +## Author Information + +Sean Sullivan and Jonathan Bouligny diff --git a/collections/ee_utilities/index.md b/collections/ee_utilities/index.md new file mode 100644 index 0000000..b04edb1 --- /dev/null +++ b/collections/ee_utilities/index.md @@ -0,0 +1,8 @@ +--- +layout: default +title: infra.ee_utilities +has_children: true +nav_order: 6 +--- + +# ee_utilities \ No newline at end of file diff --git a/collections/ee_utilities/virtualenv_migrate.md b/collections/ee_utilities/virtualenv_migrate.md new file mode 100644 index 0000000..0f806ac --- /dev/null +++ b/collections/ee_utilities/virtualenv_migrate.md @@ -0,0 +1,105 @@ +--- +layout: default +title: virtualenv_migrate +parent: infra.ee_utilities +--- + +# infra.ee_utilities.virtualenv_migrate + +Use this role to create a list of python requirements from custom virtualenvs present in your AAP 1.2 cluster, after comparing those with requirements in Default Execution Environment. +This role is based on the `awx-manage` utility and needs an AAP1.2 tower node to gather requirements from and localhost to pull EE and compare those requirements. +This role sets the python requirements to `ee_python` variable, which can then be used by the ee_utilities role to create a new EE. + +This role must be run against the tower AAP(1.2) host. As the same objects exist on multiple tower nodes in same cluster, ideally you can run this against one of those nodes and it will give sufficient results. + +This role is supposed to work with the tower AAP(1.2) nodes only, which had the ability to create custom virtualenvs instead of execution environments. + +This role should be run as root or become:true + +Sample inventory file looks like this + +```ini +[tower] +TOWER_HOST ansible_ssh_private_key=<> +``` + +## Requirements + +podman on localhost + +## Role variables + +|Variable Name|Default Value|Required|Description|Example| +|`venv_migrate_default_ee_url`|`registry.redhat.io/ansible-automation-platform-24/ee-minimal-rhel9:latest`|no|"Registry link of the EE you want to compare requirements with"|`localhost/ee:latest`| +|`registry_username`|None|yes(for default EE value)|username to sign in to the registry|`admin`| +|`registry_password`|None|yes(for default EE value)|password to sign in to the registry|`pass`| +|`ee_collections`|None|No|List of collections to add to the execution environments. Must be in a requirements.yml galaxy format.|``| +|`venv_migrate_show_diff_with_default`|`False`|No|Include default venv with the list of virtual environments scanned.|``| +|`venv_migrate_ee_python_list`|None|No|This is an output variable, if you want to pass the requirements for ee_building|debug:msg="{{ venv_migrate_ee_python_list }}"| + +## Example Playbook + +```yaml +# playbook to gather requirements from custom virtualenvs +- name: Review custom virtualenvs and pull requirements + hosts: tower + become: true + tasks: + - name: Include venv role + include_role: + name: infra.ee_utilities.virtualenv_migrate +``` + +## Example Playbook Using both roles together + +```yaml +# playbook to create EE's from an existing tower. +- name: Playbook to create custom EE + hosts: tower + gather_facts: false + collections: + - infra.ee_utilities + vars: + venv_migrate_default_ee_url: registry.redhat.io/ansible-automation-platform-24/ee-minimal-rhel9:latest + ee_collections: + - name: awx.awx + - name: infra.controller_configuration + - name: infra.ah_configuration + tasks: + - name: Include venv_migrate role + include_role: + name: infra.ee_utilities.virtualenv_migrate + + - name: ee_list + ansible.builtin.debug: + var: ee_list + +- name: Build EEs with ee_builder role + hosts: localhost + vars: + ee_registry_dest: hub + ee_ah_host: hub + ee_ah_token: f12ca3e34afcbfe2c81a563ad5446ae61cd7d530 + ee_validate_certs: false + ee_list: "{{ hostvars[groups['tower'][0]]['ee_list'] }}" + ee_image_push: false + tasks: + + - name: Create EE + include_role: + name: infra.ee_utilities.ee_builder + + - name: Export python virtual enviroment list to file + copy: + content: "{{ ee_list | to_nice_yaml( width=50, explicit_start=True, explicit_end=True) }}" + dest: venv_migrate_ee_python.yaml +... +``` + +## License + +[GPLv3+](https://github.com/redhat-cop/ee_utilities#licensing) + +## Author Information + +Anshul Behl