From 4478052b7101704caaed178cb3f210b83ec5f8d3 Mon Sep 17 00:00:00 2001 From: Alan Rominger Date: Wed, 16 Jun 2021 11:23:59 -0400 Subject: [PATCH 1/4] Update and expand docs/ folder for EEs --- docs/clustering.md | 12 +++++-- docs/execution_environments.md | 61 ++++++++++++++++++++++++++++++++++ 2 files changed, 71 insertions(+), 2 deletions(-) create mode 100644 docs/execution_environments.md diff --git a/docs/clustering.md b/docs/clustering.md index c6d5c6d7ec..32c44b1a66 100644 --- a/docs/clustering.md +++ b/docs/clustering.md @@ -181,13 +181,21 @@ If an Instance Group is configured but all instances in that group are offline o #### Project Synchronization Behavior -Project updates behave differently than they did before. Previously they were ordinary jobs that ran on a single instance. It's now important that they run successfully on any instance that could potentially run a job. Projects will sync themselves to the correct version on the instance immediately prior to running the job. If the needed revision is already locally checked out and Galaxy or Collections updates are not needed, then a sync may not be performed. +It is important that project updates run on the instance which prepares the ansible-runner private data directory. +This is accomplished by a project sync which is done by the dispatcher control / launch process. +The sync will update the source tree to the correct version on the instance immediately prior to transmitting the job. +If the needed revision is already locally checked out and Galaxy or Collections updates are not needed, then a sync may not be performed. When the sync happens, it is recorded in the database as a project update with a `launch_type` of "sync" and a `job_type` of "run". Project syncs will not change the status or version of the project; instead, they will update the source tree _only_ on the instance where they run. The only exception to this behavior is when the project is in the "never updated" state (meaning that no project updates of any type have been run), in which case a sync should fill in the project's initial revision and status, and subsequent syncs should not make such changes. +All project updates run with container isolation (like jobs) and volume mount to the persistent projects folder. + #### Controlling Where a Particular Job Runs -By default, a job will be submitted to the `tower` queue, meaning that it can be picked up by any of the workers. +By default, a job will be submitted to the default queue (formerly the `tower` queue). +To see the name of the queue, view the setting `DEFAULT_EXECUTION_QUEUE_NAME`. +Administrative actions, like project updates, will run in the control plane queue. +The name of the control plane queue is surfaced in the setting `DEFAULT_CONTROL_PLANE_QUEUE_NAME`. ##### How to Restrict the Instances a Job Will Run On diff --git a/docs/execution_environments.md b/docs/execution_environments.md new file mode 100644 index 0000000000..47a422f766 --- /dev/null +++ b/docs/execution_environments.md @@ -0,0 +1,61 @@ +# Execution Environments + +All jobs use container isolation for environment consistency and security. +Compliant images are referred to as Execution Environments (EE)s. +For more information, see [ansible-runner EE docs](https://ansible-runner.readthedocs.io/en/latest/execution_environments.html) +for information on how container isolation works, and see [ansible-builder docs](https://ansible-builder.readthedocs.io/en/latest/index.html) +for instructions on how to build them. + +The Execution Environment model has an `image` field for the image identifier which will be used by jobs. +The job details view will link to the execution environment that the job uses. + +## Creating and using EEs + +Users with and organization's `execution_environment_admin_role` can create new EEs in that organization. +The RBAC rules follow standard rules for org-scoped resources. + +Only superusers can create global EEs (null organization). +These can become the global job default in certain circumstances. + +### Pre-created EEs + +Installers should run the `awx-manage register_default_execution_environments` command to pre-populate +the system with some EEs defined in settings. This will create: + + - a control plane EE - corresponding to the `CONTROL_PLANE_EXECUTION_ENVIRONMENT` setting + - global job EEs - all images enumerated in the `GLOBAL_JOB_EXECUTION_ENVIRONMENTS` setting + +These EEs are critical for system function, so this command must be ran for AWX to be functional. +All EEs created by this command are global (do not belong to an organization). + +### Project Update EE Precedence + +Project updates will always use the control plane execution environment. + +### Job, Ad Hoc Commands, and inventory update EE Precedence + +Jobs will use the first available execution environment in this list: + +1. an EE from the template the spawned the job +2. the `default_environment` defined on the project that the job uses +3. the `default_environment` defined on the organization of the job (a direct API field) +4. the `default_environment` defined on the organization of the inventory the job uses +5. the global job default EE + +This global default job default EE will be the first available out of: + +1. the `DEFAULT_EXECUTION_ENVIRONMENT` setting +2. Any images from the `GLOBAL_JOB_EXECUTION_ENVIRONMENTS` setting +3. Any other global EEs (null organization) + +If more than 1 EE fits these criteria, then the most recently created one will be used. + +## Migrating from Custom Virtual Environments + +If you have installed dependencies inside of custom virtual environments in +a prior release, then have a look at this series of commands for help migrating +dependencies out of the venvs and into EEs. + + - `awx-manage list_custom_venvs` + - `awx-manage custom_venv_associations` + - `awx-manage export_custom_venv` From 52d6f36b7ca5cb6572e3ea6266a99fd3b6887bd8 Mon Sep 17 00:00:00 2001 From: Alan Rominger Date: Wed, 16 Jun 2021 14:24:48 -0400 Subject: [PATCH 2/4] Incorporate review comments about EE docs --- docs/execution_environments.md | 24 +++++++++++++----------- 1 file changed, 13 insertions(+), 11 deletions(-) diff --git a/docs/execution_environments.md b/docs/execution_environments.md index 47a422f766..c6c2e032d2 100644 --- a/docs/execution_environments.md +++ b/docs/execution_environments.md @@ -11,10 +11,11 @@ The job details view will link to the execution environment that the job uses. ## Creating and using EEs -Users with and organization's `execution_environment_admin_role` can create new EEs in that organization. +Users with an organization's `execution_environment_admin_role` can create new EEs in that organization. The RBAC rules follow standard rules for org-scoped resources. -Only superusers can create global EEs (null organization). +EEs without an organization (value is null in the API) are global EEs. +Only superusers can create global EEs. These can become the global job default in certain circumstances. ### Pre-created EEs @@ -26,7 +27,7 @@ the system with some EEs defined in settings. This will create: - global job EEs - all images enumerated in the `GLOBAL_JOB_EXECUTION_ENVIRONMENTS` setting These EEs are critical for system function, so this command must be ran for AWX to be functional. -All EEs created by this command are global (do not belong to an organization). +All EEs created by this command are global EEs. ### Project Update EE Precedence @@ -40,15 +41,11 @@ Jobs will use the first available execution environment in this list: 2. the `default_environment` defined on the project that the job uses 3. the `default_environment` defined on the organization of the job (a direct API field) 4. the `default_environment` defined on the organization of the inventory the job uses -5. the global job default EE +5. the current `DEFAULT_EXECUTION_ENVIRONMENT` setting +6. Any images from the `GLOBAL_JOB_EXECUTION_ENVIRONMENTS` setting +7. Any other global EEs (null organization) -This global default job default EE will be the first available out of: - -1. the `DEFAULT_EXECUTION_ENVIRONMENT` setting -2. Any images from the `GLOBAL_JOB_EXECUTION_ENVIRONMENTS` setting -3. Any other global EEs (null organization) - -If more than 1 EE fits these criteria, then the most recently created one will be used. +If more than one EE fits a criteria (applies for 5 and 6), then the most recently created one will be used. ## Migrating from Custom Virtual Environments @@ -59,3 +56,8 @@ dependencies out of the venvs and into EEs. - `awx-manage list_custom_venvs` - `awx-manage custom_venv_associations` - `awx-manage export_custom_venv` + +Follow those in order, and read the help text to see what arguments are necessary. + +You may wish to save the output from export_custom_venv command to a file with the `-q` +option, and then this can be a starting point for writing `ansible-builder` definition files. From f14129de9b1f7cdb3bb5568dfe94ed7a51e6a601 Mon Sep 17 00:00:00 2001 From: Alan Rominger Date: Wed, 16 Jun 2021 16:18:21 -0400 Subject: [PATCH 3/4] Further copy editing of EE docs --- docs/execution_environments.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/execution_environments.md b/docs/execution_environments.md index c6c2e032d2..597f1ce9d6 100644 --- a/docs/execution_environments.md +++ b/docs/execution_environments.md @@ -23,7 +23,7 @@ These can become the global job default in certain circumstances. Installers should run the `awx-manage register_default_execution_environments` command to pre-populate the system with some EEs defined in settings. This will create: - - a control plane EE - corresponding to the `CONTROL_PLANE_EXECUTION_ENVIRONMENT` setting + - the control plane EE - corresponding to the `CONTROL_PLANE_EXECUTION_ENVIRONMENT` setting - global job EEs - all images enumerated in the `GLOBAL_JOB_EXECUTION_ENVIRONMENTS` setting These EEs are critical for system function, so this command must be ran for AWX to be functional. @@ -31,21 +31,21 @@ All EEs created by this command are global EEs. ### Project Update EE Precedence -Project updates will always use the control plane execution environment. +Project updates will always use the control plane EE. ### Job, Ad Hoc Commands, and inventory update EE Precedence Jobs will use the first available execution environment in this list: -1. an EE from the template the spawned the job +1. the `execution_environment` defined on the template (job template or inventory source) that spawned the job 2. the `default_environment` defined on the project that the job uses -3. the `default_environment` defined on the organization of the job (a direct API field) +3. the `default_environment` defined on the organization of the job 4. the `default_environment` defined on the organization of the inventory the job uses -5. the current `DEFAULT_EXECUTION_ENVIRONMENT` setting -6. Any images from the `GLOBAL_JOB_EXECUTION_ENVIRONMENTS` setting -7. Any other global EEs (null organization) +5. the current `DEFAULT_EXECUTION_ENVIRONMENT` setting (configurable at `/api/v2/settings/jobs/`) +6. Any image from the `GLOBAL_JOB_EXECUTION_ENVIRONMENTS` setting +7. Any other global EE -If more than one EE fits a criteria (applies for 5 and 6), then the most recently created one will be used. +If more than one EE fits a criteria (applies for 6 and 7), then the most recently created one will be used. ## Migrating from Custom Virtual Environments From 0b6208047c038a4b718d8089dcce6ade3097cbad Mon Sep 17 00:00:00 2001 From: Alan Rominger Date: Wed, 16 Jun 2021 16:26:38 -0400 Subject: [PATCH 4/4] Correct the function of the -q option for migration helper commands --- docs/execution_environments.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/execution_environments.md b/docs/execution_environments.md index 597f1ce9d6..7d92a0fd86 100644 --- a/docs/execution_environments.md +++ b/docs/execution_environments.md @@ -59,5 +59,5 @@ dependencies out of the venvs and into EEs. Follow those in order, and read the help text to see what arguments are necessary. -You may wish to save the output from export_custom_venv command to a file with the `-q` -option, and then this can be a starting point for writing `ansible-builder` definition files. +Output from the `awx-manage export_custom_venv -q ..` command can +be a starting point for writing an `ansible-builder` definition file.