foreman_ansible_director 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a4d8ce033fdae658dc74ed39b1e726223fd1f3f709c0912500eee63a959d1cfb
-  data.tar.gz: ff49758a3a1ab2654d8af19e4841eda385c14d3338e8fc1d925cbd53863265b2
+  metadata.gz: ad5a385698810d3de3c2a7807d683ef2deacc5e12d3ec40d340ca2b3ce13b512
+  data.tar.gz: 396708fd055a23d192e4355d08fe5a76396869d8ec36785c4951cc9572268e13
 SHA512:
-  metadata.gz: c65a3a229e2b3d482e3144dcfd0eb8a4c5de8e70acc1a089f09234686267ac0c597f98b9308e8b1d438be43c7e0b5301ee9e3d2ea86558656e2b52482e38897f
-  data.tar.gz: 165890d464e01ce17f4e673fe7ab88d4c391a28a34ce37f13274c1459d5fe37613c8ed8e4d3daf84ca14cc37a276a3f9400fb9647c09c0b6df11f625901bb9d3
+  metadata.gz: de0b152a577bfc6cd2f45bb43ee16d456fbd15146510fe6429158cf05a2bad4d6ed1f963131e12e27fd74524bafacb85fb2737ab2c3886be277632889d827ead
+  data.tar.gz: 28b6076faaae3c7b027cfe31528d5ea650e88cd0bd682a93d7feca85ae7660a976e628c3d5aac0334fde8dc6b420911873249d9716f2d3fab3e20424e1ec606b

data/app/controllers/foreman_ansible_director/api/v2/ansible_content_controller.rb

@@ -7,8 +7,54 @@ module ForemanAnsibleDirector
         before_action :find_organization, only: %i[create_units]
         before_action :find_optional_organization, only: %i[index]
 
-        # TODO: APIDOC
+        resource_description { resource_id 'AD Ansible Content' }
 
+        # region ApiDoc: POST /api/v2/ansible_director/ansible_content
+        api :POST, '/v2/ansible_director/ansible_content', N_('Import Ansible content units')
+        param :organization_id, :number, desc: N_('Organization identifier.'), required: true
+        param :units, Array, desc: N_('Array of content units to import.'), required: true do
+          param :unit_name,
+            String,
+            desc: N_('Identifier of the content unit.'),
+            example: N_('manala.roles'),
+            required: true
+          param :unit_type,
+            %w[role collection],
+            desc: N_('Type of the content unit.'),
+            example: N_('collection'),
+            required: true
+          param :unit_source_type,
+            %w[galaxy git],
+            desc: N_('Source type of the content unit.'),
+            example: N_('galaxy'),
+            required: true
+          param :unit_source,
+            String,
+            desc: N_('Source URL or path for the content unit (e.g., Galaxy URL or Git repo).'),
+            example: N_('https://galaxy.ansible.com'),
+            required: true
+          param :unit_versions,
+            Array,
+            desc: N_('An array of versions to import (e.g., ["1.0.0", "2.0.0"]).'),
+            example: %w[1.0.0 2.0.0],
+            required: true
+        end
+        # TRANSLATORS: ApiDoc, do not translate!
+        example <<~EXAMPLE
+          {
+            "organization_id": 1,
+            "units": [
+              {
+                "unit_name": "manala.roles",
+                "unit_type": "collection",
+                "unit_source_type": "galaxy",
+                "unit_source": "https://galaxy.ansible.com",
+                "unit_versions": ["5.2.0"]
+              }
+            ]
+          }
+        EXAMPLE
+        # endregion
         def create_units
           resolved = ::ForemanAnsibleDirector::AnsibleContent::AnsibleContentHelpers.resolve_import_payload(
             params[:units]
@@ -20,6 +66,11 @@ module ForemanAnsibleDirector
           )
         end
 
+        # region ApiDoc: GET /api/v2/ansible_director/ansible_content
+        api :GET, '/v2/ansible_director/ansible_content', N_('List Ansible content units')
+        param :organization_id, :number, desc: N_('Organization identifier'), required: false
+        param_group :search_and_pagination, ::Api::V2::BaseController
+        # endregion
         def index
           scope = resource_scope_for_index
           @ansible_content_units = if @organization
@@ -29,18 +80,51 @@ module ForemanAnsibleDirector
                                    end
         end
 
+        # region ApiDoc: GET /api/v2/ansible_director/ansible_content/:content_unit_id/versions/:content_unit_version_id
+        api :GET, '/v2/ansible_director/ansible_content/:content_unit_id/versions/:content_unit_version_id',
+          N_('Show details of a specific Ansible content unit version')
+        # endregion
         def version_detail
           @content_unit_version = ::ForemanAnsibleDirector::ContentUnitVersion.find_by(id: params[:version])
         end
 
         # TODO: This needs to check and invalidate built EEs
+        # region ApiDoc: DELETE /api/v2/ansible_director/ansible_content
+        api :DELETE, '/v2/ansible_director/ansible_content',
+          N_('Destroy previously imported Ansible content units.')
+        param :units, Array, desc: N_('Array of content units to destroy.'), required: true do
+          param :unit_id, :number, desc: N_('ID of the Ansible content unit to destroy.'), required: true
+          # TRANSLATORS: ApiDoc, do not translate!
+          param :unit_version_ids, Array,
+            desc: <<~DESC,
+              Array of version IDs to delete.
+              Optional: If not supplied, every version of the given content unit will be deleted.
+            DESC
+            required: false
+        end
+        # TRANSLATORS: ApiDoc, do not translate!
+        example <<~EXAMPLE
+          {
+            "units": [
+              {
+                "unit_id": 42,
+                "unit_version_ids": [101, 102]
+              },
+              {
+                "unit_id": 43,
+                "unit_version_ids": [105]
+              }
+            ]
+          }
+        EXAMPLE
+        # endregion
         def destroy_units
           resolved = ::ForemanAnsibleDirector::AnsibleContent::AnsibleContentHelpers.resolve_destroy_payload(
             destroy_params
           )
           @bulk_destroy_task =
             ForemanTasks.sync_task(::ForemanAnsibleDirector::Actions::AnsibleContentUnit::Bulk::Destroy,
-              resolved_content_units: resolved, organization_id: @organization.id)
+              resolved_content_units: resolved)
         end
 
         def model_of_controller

data/app/controllers/foreman_ansible_director/api/v2/ansible_variable_overrides_controller.rb

@@ -7,6 +7,30 @@ module ForemanAnsibleDirector
         before_action :find_variable, only: %i[create]
         before_action :find_override, only: %i[update destroy]
 
+        resource_description { resource_id 'AD Ansible Variable Overrides' }
+
+        # region ApiDoc: GET /api/v2/ansible_director/ansible_variables/:ansible_variable_id/overrides
+        api :GET, '/v2/ansible_director/ansible_variables/:ansible_variable_id/overrides',
+          N_('List overrides for a target')
+        # TRANSLATORS: ApiDoc, do not translate!
+        description <<~DESC
+          List override values associated with a given target (host or hostgroup).
+          Overrides are matched at runtime based on the predefined hierarchy: Default -> Hostgroup -> Host.
+        DESC
+        param :target,
+          %w[HOST HOSTGROUP],
+          desc: N_('Type of the target entity.'),
+          required: true
+        param :target_id,
+          :number,
+          desc: N_('ID of the target entity.'),
+          required: true
+        param :include_overridable,
+          [true, false],
+          desc: N_('Whether to include overridable variables in the response.'),
+          example: false,
+          required: false
+        # endregion
         def index_for_target
           target = ::ForemanAnsibleDirector::AssignmentService.find_target(
             target_type: params[:target],
@@ -17,6 +41,46 @@ module ForemanAnsibleDirector
             include_overridable: include_overridable
         end
 
+        # region ApiDoc: POST /api/v2/ansible_director/ansible_variables/:ansible_variable_id/overrides
+        api :POST, '/v2/ansible_director/ansible_variables/:ansible_variable_id/overrides',
+          N_('Create an override for an Ansible variable')
+        # TRANSLATORS: ApiDoc, do not translate!
+        description <<~DESC
+          Create a new override rule for the specified Ansible variable.
+          Overrides allow customizing the variable value for specific hosts, hostgroups, or other matchers.
+        DESC
+        param :ansible_variable_id,
+          :number,
+          desc: N_('ID of the Ansible variable to override.'),
+          required: true
+        param :override, Hash, desc: N_('Override definition'), required: true do
+          param :value,
+            String,
+            desc: N_('Override value (must be valid JSON when the variable type is `json`, `array`, or `hash`).'),
+            example: '192.168.1.1',
+            required: true
+          param :matcher,
+            %w[fqdn hostgroup],
+            desc: N_('Matcher type.'),
+            example: 'fqdn',
+            required: true
+          param :matcher_value,
+            String,
+            desc: N_('Value for the matcher (e.g., "myhost.example.com").'),
+            example: 'myhost.example.com',
+            required: true
+        end
+        # TRANSLATORS: ApiDoc, do not translate!
+        example <<~EXAMPLE
+          {
+            "override": {
+              "value": "prod-ntp.internal",
+              "matcher": "fqdn",
+              "matcher_value": "prod-web-01.example.com"
+            }
+          }
+        EXAMPLE
+        # endregion
         def create
           override = override_params
           ::ForemanAnsibleDirector::VariableService.create_override(
@@ -27,6 +91,48 @@ module ForemanAnsibleDirector
           )
         end
 
+        # region ApiDoc: PUT /api/v2/ansible_director/ansible_variables/:ansible_variable_id/overrides/:id
+        api :PUT, '/v2/ansible_director/ansible_variables/:ansible_variable_id/overrides/:id', N_('Update an override')
+        # TRANSLATORS: ApiDoc, do not translate!
+        description <<~DESC
+          Update an existing override rule.
+        DESC
+        param :ansible_variable_id,
+          :number,
+          desc: N_('ID of the Ansible variable.'),
+          required: true
+        param :id,
+          :number,
+          desc: N_('ID of the override to update.'),
+          required: true
+        param :override, Hash, desc: N_('Override update'), required: true do
+          param :value,
+            String,
+            desc: N_('New override value.'),
+            example: 'backup-ntp.internal',
+            required: false
+          param :matcher,
+            String,
+            desc: N_('New matcher type (e.g., "hostgroup").'),
+            example: 'hostgroup',
+            required: false
+          param :matcher_value,
+            String,
+            desc: N_('New matcher value (e.g., "my_hostgroup").'),
+            example: 'my_hostgroup',
+            required: false
+        end
+        # TRANSLATORS: ApiDoc, do not translate!
+        example <<~EXAMPLE
+          {
+            "override": {
+              "value": "staging-ntp.internal",
+              "matcher": "hostgroup",
+              "matcher_value": "Staging"
+            }
+          }
+        EXAMPLE
+        # endregion
         def update
           override = override_params
           ::ForemanAnsibleDirector::VariableService.edit_override(
@@ -37,6 +143,22 @@ module ForemanAnsibleDirector
           )
         end
 
+        # region ApiDoc: DELETE /api/v2/ansible_director/ansible_variables/:ansible_variable_id/overrides/:id
+        api :DELETE, '/v2/ansible_director/ansible_variables/:ansible_variable_id/overrides/:id',
+          N_('Delete an override')
+        # TRANSLATORS: ApiDoc, do not translate!
+        description <<~DESC
+          Delete an override rule.
+        DESC
+        param :ansible_variable_id,
+          :number,
+          desc: N_('ID of the Ansible variable.'),
+          required: true
+        param :id,
+          :number,
+          desc: N_('ID of the override to delete.'),
+          required: true
+        # endregion
         def destroy
           ::ForemanAnsibleDirector::VariableService.destroy_override(@override)
         end

data/app/controllers/foreman_ansible_director/api/v2/ansible_variables_controller.rb

@@ -6,9 +6,58 @@ module ForemanAnsibleDirector
       class AnsibleVariablesController < AnsibleDirectorApiController
         before_action :find_resource, only: %i[show update]
 
+        resource_description { resource_id 'AD Ansible Variables' }
+
+        # region ApiDoc: GET /api/v2/ansible_director/ansible_variables/:id
+        api :GET, '/v2/ansible_director/ansible_variables/:id', N_('Show details of an Ansible variable')
+        # TRANSLATORS: ApiDoc, do not translate!
+        description <<~DESC
+          Retrieve details of a specific Ansible variable.
+        DESC
+        # endregion
         def show
         end
 
+        # region ApiDoc: PUT /api/v2/ansible_director/ansible_variables/:id
+        api :PUT, '/v2/ansible_director/ansible_variables/:id', N_('Update an Ansible variable')
+        # TRANSLATORS: ApiDoc, do not translate!
+        description <<~DESC
+          Update basic attributes (key, type, default value, and overridability) of an Ansible variable.
+        DESC
+        param :ansible_variable, Hash, desc: N_('Ansible variable updates'), required: true do
+          param :key,
+            String,
+            desc: N_('Name of the variable.'),
+            example: 'ansible_user',
+            required: true
+          param :type,
+            %w[string integer boolean float json array hash],
+            desc: N_('Type of the variable value.'),
+            example: 'string',
+            required: true
+          param :default_value,
+            String,
+            desc: N_('Default value (must be valid JSON when type is `json`, `array`, or `hash`).'),
+            example: 'root',
+            required: true
+          param :overridable,
+            [true, false],
+            desc: N_('Whether this variable can be overridden on hosts or hostgroups.'),
+            example: true,
+            required: false
+        end
+        # TRANSLATORS: ApiDoc, do not translate!
+        example <<~EXAMPLE
+          {
+            "ansible_variable": {
+              "key": "ansible_user",
+              "type": "string",
+              "default_value": "root",
+              "overridable": true
+            }
+          }
+        EXAMPLE
+        # endregion
         def update
           variable = variable_params
           ::ForemanAnsibleDirector::VariableService.edit_variable(

data/app/controllers/foreman_ansible_director/api/v2/assignments_controller.rb

@@ -6,6 +6,28 @@ module ForemanAnsibleDirector
       class AssignmentsController < AnsibleDirectorApiController
         before_action :find_resource, only: %i[destroy]
 
+        resource_description { resource_id 'AD Ansible Content Assignments' }
+
+        # region ApiDoc: GET /api/v2/ansible_director/assignments
+        api :GET, '/v2/ansible_director/assignments', N_('List resolved Ansible content assignments for a target')
+        # TRANSLATORS: ApiDoc, do not translate!
+        description <<~DESC
+          Retrieve all Ansible content units *resolved* for a given target (host or hostgroup).
+          This includes content inherited through the assignment hierarchy or direct assignments.
+        DESC
+        param :target,
+          %w[HOST HOSTGROUP],
+          desc: N_('Type of the target entity.'),
+          required: true
+        param :target_id,
+          :number,
+          desc: N_('ID of the target entity.'),
+          required: true
+        # TRANSLATORS: ApiDoc, do not translate!
+        example <<~EXAMPLE
+          GET /api/v2/ansible_director/assignments?target=HOST&target_id=123
+        EXAMPLE
+        # endregion
         def assignments
           target = ::ForemanAnsibleDirector::AssignmentService.find_target(
             target_type: params[:target],
@@ -15,6 +37,54 @@ module ForemanAnsibleDirector
           @assignments = target.resolved_ansible_content
         end
 
+        # region ApiDoc: POST /api/v2/ansible_director/assignments
+        api :POST, '/v2/ansible_director/assignments', N_('Assign Ansible content to a target')
+        # TRANSLATORS: ApiDoc, do not translate!
+        description <<~DESC
+          Assign Ansible content from a source (e.g., a lifecycle environment) to a target.
+        DESC
+        param :assignment, Hash, desc: N_('Assignment definition'), required: true do
+          param :source, Hash, desc: N_('Source (provider of content)'), required: true do
+            param :type,
+              %w[ACR],
+              desc: N_('Type of source. Currently, only Ansible collection roles (ACR) are supported as sources.'),
+              example: 'ACR',
+              required: true
+            param :id,
+              :number,
+              desc: N_('ID of the source entity.'),
+              example: 5,
+              required: true
+          end
+          param :target, Hash, desc: N_('Target (receiver of content)'), required: true do
+            param :type,
+              %w[HOST HOSTGROUP],
+              desc: N_('Type of target. Both hosts (HOST) and hostgroups (HOSTGROUP) are supported as targets.'),
+              example: 'HOST',
+              required: true
+            param :id,
+              :number,
+              desc: N_('ID of the target entity.'),
+              example: 6,
+              required: true
+          end
+        end
+        # TRANSLATORS: ApiDoc, do not translate!
+        example <<~EXAMPLE
+          {
+            "assignment": {
+              "source": {
+                "type": "ACR",
+                "id": 109
+              },
+              "target": {
+                "type": "HOST",
+                "id": 1
+              }
+            }
+          }
+        EXAMPLE
+        # endregion
         def assign
           assignment = assignment_params
 
@@ -34,6 +104,57 @@ module ForemanAnsibleDirector
           )
         end
 
+        # region ApiDoc: POST /api/v2/ansible_director/assignments/bulk
+        api :POST, '/v2/ansible_director/assignments/bulk', N_('Bulk assign Ansible content')
+        # TRANSLATORS: ApiDoc, do not translate!
+        description <<~DESC
+          Bulk-assign Ansible content from a source (e.g., a lifecycle environment) to targets.
+          Equivalent to calling `/assign` multiple times.
+        DESC
+        param :assignments, Array, desc: N_('Array of assignment objects'), required: true do
+          param :source, Hash, desc: N_('Source (provider of content)'), required: true do
+            param :type,
+              %w[ACR],
+              desc: N_('Type of source. Currently, only Ansible collection roles (ACR) are supported as sources.'),
+              example: 'ACR',
+              required: true
+            param :id,
+              :number,
+              desc: N_('ID of the source entity.'),
+              example: 5,
+              required: true
+          end
+          param :target, Hash, desc: N_('Target (receiver of content)'), required: true do
+            param :type,
+              %w[HOST HOSTGROUP],
+              desc: N_('Type of target. Both hosts (HOST) and hostgroups (HOSTGROUP) are supported as targets.'),
+              example: 'HOST',
+              required: true
+            param :id,
+              :number,
+              desc: N_('ID of the target entity.'),
+              example: 6,
+              required: true
+          end
+        end
+        # TRANSLATORS: ApiDoc, do not translate!
+        example <<~EXAMPLE
+          {
+            "assignments": [
+              {
+                "source": {
+                  "type": "ACR",
+                  "id": 109
+                },
+                "target": {
+                  "type": "HOST",
+                  "id": 1
+                }
+              }
+            ]
+          }
+        EXAMPLE
+        # endregion
         def assign_bulk
           assignments = bulk_assignment_params
           ::ForemanAnsibleDirector::AssignmentService.create_bulk_assignments(
@@ -41,6 +162,17 @@ module ForemanAnsibleDirector
           )
         end
 
+        # region ApiDoc: DELETE /api/v2/ansible_director/assignments/:id
+        api :DELETE, '/v2/ansible_director/assignments/:id', N_('Delete an Ansible content assignment')
+        # TRANSLATORS: ApiDoc, do not translate!
+        description <<~DESC
+          Note: This deletes the assignment record but not the underlying Ansible content.
+        DESC
+        param :id,
+          :number,
+          desc: N_('ID of the assignment to delete.'),
+          required: true
+        # endregion
         def destroy
           ::ForemanAnsibleDirector::AssignmentService.destroy_assignment(@assignment)
         end

data/app/controllers/foreman_ansible_director/api/v2/execution_environments_controller.rb

@@ -9,10 +9,54 @@ module ForemanAnsibleDirector
         before_action :find_resource, only: %i[update destroy]
         before_action :find_organization, only: %i[create]
 
+        resource_description { resource_id 'AD Ansible Execution Environments' }
+
+        # region ApiDoc: GET /api/v2/ansible_director/execution_environments
+        api :GET, '/v2/ansible_director/execution_environments', N_('List all execution environments')
+        param :organization_id, :number, desc: N_('Organization identifier.'), required: false
+        param_group :search_and_pagination, ::Api::V2::BaseController
+        # endregion
         def index
           @execution_environments = resource_scope_for_index
         end
 
+        # region ApiDoc: POST /api/v2/ansible_director/execution_environments
+        api :POST, '/v2/ansible_director/execution_environments', N_('Create an Execution Environment')
+        param :organization_id, :number, desc: N_('Organization identifier'), required: true
+        param :execution_environment, Hash, desc: N_('Execution Environment definition'), required: true do
+          param :name,
+            String,
+            desc: N_('Execution Environment name.'),
+            example: 'MyExecutionEnvironment',
+            required: true
+          param :base_image_url,
+            String,
+            desc: N_('Execution Environment base image URL. The image must be pullable by an unauthenticated user.'),
+            example: 'registry.fedoraproject.org/fedora:43',
+            required: true
+          # TRANSLATORS: ApiDoc, do not translate!
+          param :ansible_version,
+            String,
+            desc: <<~DESC,
+              Version of "ansible-core" to be used in this execution environment.
+              The version must match one of the available releases.
+              See: https://pypi.org/project/ansible-core/#history
+            DESC
+            example: ::ForemanAnsibleDirector::Constants::DEFAULT_ANSIBLE_VERSION,
+            required: true
+        end
+        # TRANSLATORS: ApiDoc, do not translate!
+        example <<~EXAMPLE
+          {
+            "organization_id": 1,
+            "execution_environment": {
+              "name": "EE-2.20.0",
+              "base_image_url": "quay.io/fedora/fedora:42",
+              "ansible_version": "2.20.0"
+            }
+          }
+        EXAMPLE
+        # endregion
         def create
           permitted_params = execution_environment_params
           # content = permitted_params.delete(:content)
@@ -25,6 +69,41 @@ module ForemanAnsibleDirector
           )
         end
 
+        # region ApiDoc: PATCH /api/v2/ansible_director/execution_environments/:id
+        api :PATCH, '/v2/ansible_director/execution_environments/:id', N_('Update an Execution Environment')
+        param :execution_environment, Hash, desc: N_('Execution Environment definition'), required: true do
+          param :name,
+            String,
+            desc: N_('Execution Environment name.'),
+            example: 'MyExecutionEnvironment',
+            required: false
+          param :base_image_url,
+            String,
+            desc: N_('Execution Environment base image URL. The image must be pullable by an unauthenticated user.'),
+            example: 'registry.fedoraproject.org/fedora:43',
+            required: false
+          # TRANSLATORS: ApiDoc, do not translate!
+          param :ansible_version,
+            String,
+            desc: <<~DESC,
+              Version of "ansible-core" to be used in this execution environment.
+              The version must match one of the available releases.
+              See: https://pypi.org/project/ansible-core/#history
+            DESC
+            example: ::ForemanAnsibleDirector::Constants::DEFAULT_ANSIBLE_VERSION,
+            required: false
+        end
+        # TRANSLATORS: ApiDoc, do not translate!
+        example <<~EXAMPLE
+          {
+            "execution_environment": {
+              "name": "EE-2.20.0",
+              "base_image_url": "quay.io/fedora/fedora:42",
+              "ansible_version": "2.20.0"
+            }
+          }
+        EXAMPLE
+        # endregion
         def update
           permitted_params = execution_environment_params
           # content = permitted_params.delete(:content)
@@ -37,6 +116,9 @@ module ForemanAnsibleDirector
           )
         end
 
+        # region ApiDoc: DELETE /api/v2/ansible_director/execution_environments/:id
+        api :DELETE, '/v2/ansible_director/execution_environments/:id', N_('Delete an Execution Environment')
+        # endregion
         def destroy
           @execution_environment.destroy
           ::ForemanAnsibleDirector::ExecutionEnvironmentService.destroy_execution_environment @execution_environment