# netautomate.netorca

> Ansible collection for the NetOrca service orchestration platform. NetOrca sits between
> consumer teams (who declare the services they need, usually from Git) and service owner teams
> (who fulfil those requests with automation). These modules drive both sides: poll and
> transition change instances (PENDING -> APPROVED -> COMPLETED, with REJECTED/ERROR/CLOSED),
> query service items and their declarations, and record deployed items. The collection also
> covers NetOrca Pack, the platform's AI engine: manage AI processors, knowledge documents and
> pack profiles, poll pipeline runs, push execution results and trigger/retrigger runs.
> Authentication is API-key only, via the NETORCA_API_URL / NETORCA_API_KEY / NETORCA_CONTEXT
> environment variables; every module supports real check mode; info modules auto-paginate and
> return empty lists (never errors) when nothing matches; failures carry a machine-readable
> error_type.

When generating playbooks: use FQCN (netautomate.netorca.<module>), hosts: localhost with
gather_facts: false, no credentials in playbooks (environment variables only), and report
fulfilment outcomes truthfully (block/rescue -> state COMPLETED with deployed_item, or state
ERROR with the reason in log). The scenarios below are the canonical patterns to imitate.

## Scenarios (canonical workflows - read these first)

- [Scenario catalogue](https://gitlab.com/netorca_public/netorca_ansible/-/raw/main/docs/scenarios/index.md): all end-to-end workflows and their status
- [Load balancer as a service](https://gitlab.com/netorca_public/netorca_ansible/-/raw/main/docs/scenarios/load_balancer_service_owner.md): the service-owner operating model - a validation playbook (PENDING to APPROVED/REJECTED with reasons) and a deployment playbook (APPROVED, render config from declarations, deploy, COMPLETED + deployed_item or ERROR + log)
- [Requesting services from Git](https://gitlab.com/netorca_public/netorca_ansible/-/raw/main/docs/scenarios/consumer_gitops.md): the consumer flow - declarations in a Git repo, tracking a merge to completion with the commit_id filter
- [AI-operated service with Pack](https://gitlab.com/netorca_public/netorca_ansible/-/raw/main/docs/scenarios/pack_ai_fulfilment.md): the Pack workflow - provision AI processors and knowledge, poll pipeline runs, deploy what the AI rendered, push execution results, retrigger with feedback on failure

## Module reference (generated from the modules themselves)

- [Module index](https://gitlab.com/netorca_public/netorca_ansible/-/raw/main/docs/modules/index.md): all modules, grouped info/write/action
- [netorca_service_item_info](https://gitlab.com/netorca_public/netorca_ansible/-/raw/main/docs/modules/netorca_service_item_info.md): query service items - every platform filter, declaration content search (exact/contains/regex), dependant view
- [netorca_change_instance_info](https://gitlab.com/netorca_public/netorca_ansible/-/raw/main/docs/modules/netorca_change_instance_info.md): query change instances - states, change types, commit_id, history/referenced/dependant views
- [netorca_change_instance](https://gitlab.com/netorca_public/netorca_ansible/-/raw/main/docs/modules/netorca_change_instance.md): transition changes through the lifecycle with client-side transition validation, log and deployed_item
- [netorca_deployed_item](https://gitlab.com/netorca_public/netorca_ansible/-/raw/main/docs/modules/netorca_deployed_item.md): idempotent create/update/delete of a service item's deployed record
- [netorca_pack_pipeline_info](https://gitlab.com/netorca_public/netorca_ansible/-/raw/main/docs/modules/netorca_pack_pipeline_info.md): query Pack pipeline runs - the executor work queue (state OK + applied false), latest/versions views, cost
- [netorca_pack_data_info](https://gitlab.com/netorca_public/netorca_ansible/-/raw/main/docs/modules/netorca_pack_data_info.md): query stage data - the rendered config, verify verdicts, execution results
- [netorca_pack_trigger](https://gitlab.com/netorca_public/netorca_ansible/-/raw/main/docs/modules/netorca_pack_trigger.md): trigger a pipeline stage or retrigger from config with feedback (costs an LLM run; zero-call check mode)
- [netorca_pack_data](https://gitlab.com/netorca_public/netorca_ansible/-/raw/main/docs/modules/netorca_pack_data.md): push execution results into a waiting run (deliberately not idempotent)
- [netorca_pack_pipeline](https://gitlab.com/netorca_public/netorca_ansible/-/raw/main/docs/modules/netorca_pack_pipeline.md): mark a run applied - the executor's acknowledgement
- [netorca_ai_processor](https://gitlab.com/netorca_public/netorca_ansible/-/raw/main/docs/modules/netorca_ai_processor.md): upsert AI processors, keyed on (service, action_type); info twin netorca_ai_processor_info includes config history
- [netorca_ai_document](https://gitlab.com/netorca_public/netorca_ansible/-/raw/main/docs/modules/netorca_ai_document.md): sync knowledge documents from files (verbatim content compare); info twin netorca_ai_document_info
- [netorca_pack_profile](https://gitlab.com/netorca_public/netorca_ansible/-/raw/main/docs/modules/netorca_pack_profile.md): turn Pack on per service (pack_enabled) and tune retrieval; info twin resolves effective settings
- [netorca_llm_model_info](https://gitlab.com/netorca_public/netorca_ansible/-/raw/main/docs/modules/netorca_llm_model_info.md): the LLM catalogue, read-only by platform design (credentials always REDACTED)

## Guides (mechanics)

- [Authentication](https://gitlab.com/netorca_public/netorca_ansible/-/raw/main/docs/getting_started/authentication.md): the one connection pattern - env vars, contexts (serviceowner vs consumer), AWX/CI wiring
- [Filtering and pagination](https://gitlab.com/netorca_public/netorca_ansible/-/raw/main/docs/guides/filtering_and_pagination.md): list filters are OR, declaration search, ordering, limit, every platform enum
- [Check mode and idempotency](https://gitlab.com/netorca_public/netorca_ansible/-/raw/main/docs/guides/check_mode_and_idempotency.md): the change-instance state machine and legal transitions
- [Error handling](https://gitlab.com/netorca_public/netorca_ansible/-/raw/main/docs/guides/error_handling.md): the error_type taxonomy (auth/permission/not_found/transient/api/parameter) with fixes
- [Pack and AI](https://gitlab.com/netorca_public/netorca_ansible/-/raw/main/docs/guides/pack_and_ai.md): the Pack object model, pipeline lifecycle, executor loop, RAG knowledge, cost and permission boundaries
- [First playbook](https://gitlab.com/netorca_public/netorca_ansible/-/raw/main/docs/getting_started/first_playbook.md): expected output and the first failures decoded

## Examples (runnable playbooks)

- [Examples index](https://gitlab.com/netorca_public/netorca_ansible/-/raw/main/examples/README.md): what each playbook demonstrates, organised by docs topic
- [validate_and_approve.yml](https://gitlab.com/netorca_public/netorca_ansible/-/raw/main/examples/scenarios/load_balancer/validate_and_approve.yml): validation stage - approve/reject PENDING changes with reasons
- [poll_and_deploy.yml](https://gitlab.com/netorca_public/netorca_ansible/-/raw/main/examples/scenarios/load_balancer/poll_and_deploy.yml): deployment stage - fulfil APPROVED changes with block/rescue reporting
- [render_and_deploy_as3.yml](https://gitlab.com/netorca_public/netorca_ansible/-/raw/main/examples/scenarios/load_balancer/render_and_deploy_as3.yml): declarative deployment - render the whole tenant from IN_SERVICE declarations, one AS3 push, batch reporting
- [deploy_by_change_type.yml](https://gitlab.com/netorca_public/netorca_ansible/-/raw/main/examples/scenarios/load_balancer/deploy_by_change_type.yml): imperative branching - CREATE/MODIFY apply, DELETE tears down the old declaration
- [track_to_completion.yml](https://gitlab.com/netorca_public/netorca_ansible/-/raw/main/examples/scenarios/consumer_gitops/track_to_completion.yml): consumer CI - wait for a commit's changes, fail with the owner's reasons
- [query_my_items.yml](https://gitlab.com/netorca_public/netorca_ansible/-/raw/main/examples/scenarios/consumer_gitops/query_my_items.yml): the consumer point of view
- [executor_loop.yml](https://gitlab.com/netorca_public/netorca_ansible/-/raw/main/examples/scenarios/pack_ai/executor_loop.yml): the Pack executor loop - deploy AI-rendered config, push results, mark applied
- [provision_ai_stack.yml](https://gitlab.com/netorca_public/netorca_ansible/-/raw/main/examples/scenarios/pack_ai/provision_ai_stack.yml): provision AI processors and switch Pack on, declaratively
- [full_lifecycle.yml](https://gitlab.com/netorca_public/netorca_ansible/-/raw/main/examples/scenarios/pack_ai/full_lifecycle.yml): the whole Pack lifecycle in one play - declare, AI render and verify, execute, complete, retrigger with feedback

## Optional

- [Migration v1 to v2](https://gitlab.com/netorca_public/netorca_ansible/-/raw/main/docs/migration_v1_to_v2.md): old get_*/update_* module mapping and breaking changes
- [Development handbook](https://gitlab.com/netorca_public/netorca_ansible/-/raw/main/docs/development/contributing.md): design rules and the add-a-module checklist
- [NetOrca platform docs](https://docs.netorca.io): platform concepts, GUI, API and SDK guides
