netorca_service_item_info - Query service items in NetOrca

Part of the netautomate.netorca collection (version 2.0.0). Added in version 2.0.0.

Synopsis

• Retrieve service items from NetOrca, with every filter the platform supports exposed as a validated module parameter.
• A service item is one consumed instance of a service, created from a consumer team's declaration. It carries the currently declared state (its declaration), a lifecycle runtime_state and an aggregated change_state that summarises its open change instances.
• Service owners use this module to inventory everything consumers have declared against their services - for example to render the complete desired state of the infrastructure from the returned declarations. To fetch the work queue of requested changes instead, use netautomate.netorca.netorca_change_instance_info.
• Consumers use it (with context=consumer) to list the service items their own applications declared.
• Search inside declarations with declaration (exact), declaration_regex and declaration_contains - handy to answer questions like which load balancers sit in a given partition.

Requirements

The below requirements are needed on the host that executes this module.

• netorca-sdk >= 1.0.9, < 2.0.0

Parameters

Parameter	Comments
application_id list / elements=int	Filter by ID of the consumer application the item belongs to.
application_name list / elements=str	Filter by exact name of the consumer application the item belongs to.
application_name_contains str	Filter by application name (substring match).
change_state list / elements=str	Filter by the aggregated state of the item's change instances - for example CHANGES_APPROVED finds items with approved work waiting to be deployed and ALL_CHANGES_COMPLETED finds items with nothing outstanding. Choices: ALL_CHANGES_COMPLETED, CHANGES_PENDING, CHANGES_ERRORED, CHANGES_REJECTED, CHANGES_APPROVED
consumer_team_id list / elements=int	Filter by ID of the consuming team - the team whose application declared the item.
declaration dict	Filter by exact match on declaration fields - every key/value pair must equal the corresponding field of the item's declaration, for example {"partition": "prod"}.
declaration_contains dict	Filter by containment match on declaration fields - values match if they are contained in the corresponding field, for example {"comments": "web"}.
declaration_regex dict	Filter by regular expression match on declaration fields - values are regexes matched against the corresponding field, for example {"name": "^prod-.*"}.
dependant bool	Query the dependant view (service_items/dependant) instead of the plain listing. Lists the service items your team contributes to because the owning service declares your team in its dependant_teams (see the NetOrca documentation on dependant teams). Default: false
id int	Return only the service item with this ID. When set, all other filters are ignored. If the ID does not exist, an empty list is returned.
name str	Filter by service item name (case-insensitive substring match).
runtime_state list / elements=str	Filter by lifecycle state - REQUESTED (declared, CREATE change not yet completed), IN_SERVICE (deployed) or DECOMMISSIONED (DELETE change completed). The platform excludes DECOMMISSIONED items from listings unless this filter is set. Choices: REQUESTED, IN_SERVICE, DECOMMISSIONED
service_id list / elements=int	Filter by service ID.
service_name list / elements=str	Filter by exact service name, for example LOAD_BALANCER. This is usually the first filter a service owner sets - it scopes the query to one of the services the team offers.
service_owner_id list / elements=int	Filter by ID of the service owner.
service_owner_team_id list / elements=int	Filter by ID of the team that owns the service.

Common parameters

Connection and query parameters shared by every module in the collection. See Authentication for the environment-variable pattern.

Parameter	Comments
context str	Point of view for the request. The same query returns different data depending on which side of the service relationship your team is on. serviceowner operates on the services your team offers - the requests made against them, their service items and deployed items. This is the side that validates, approves, deploys and completes changes. consumer operates on what your team consumes - the service items your applications declared and the change instances tracking your own requests. If not set, the value of the NETORCA_CONTEXT environment variable is used. Choices: serviceowner, consumer Default: serviceowner
limit int	Maximum number of results to return. Results are auto-paginated, so by default all matching records are returned regardless of the API's page size.
ordering str	Server-side field to order results by, for example created or modified. Prefix with - for descending order - -modified returns the most recently changed records first.
api_url str required	Base URL of the NetOrca API, for example https://api.example.netorca.io. The URL is normalised to end in a single /v1, so passing it with or without the suffix both work. If not set, the value of the NETORCA_API_URL environment variable is used.
api_key str required	API key of your NetOrca team. The NetOrca API supports API-key authentication only - there is no username/password mode. Treat the key like a password - supply it via the NETORCA_API_KEY environment variable (for example from a CI/CD secret) or from Ansible Vault, never as a literal in a playbook. If not set, the value of the NETORCA_API_KEY environment variable is used.
validate_certs bool	Whether to validate TLS certificates when talking to the API. Only disable this for lab instances with self-signed certificates. If not set, the value of the NETORCA_VALIDATE_CERTS environment variable is used. Default: true

Attributes

Attribute	Support	Description
check_mode	full	This module is read-only and runs identically with and without check mode.
diff_mode	N/A	This module never changes anything, so there is nothing to diff.

Notes

• All modules talk to the NetOrca REST API and are typically executed on the controller (hosts=localhost with gather_facts=false, or delegate_to=localhost).
• Module parameters take precedence over their NETORCA_* environment variable fallbacks.
• Info modules never change anything and always return changed=false.
• When nothing matches - including a lookup by ID that does not exist - info modules return an empty list rather than failing.
• Filter options that accept a list match records with any of the given values (an OR filter, the platform's in lookup).

Examples

# Authentication in all examples comes from the NETORCA_API_URL / NETORCA_API_KEY
# environment variables; pass api_url / api_key parameters to override.

- name: Get all service items of my services
  netautomate.netorca.netorca_service_item_info:
  register: items

- name: All in-service LOAD_BALANCER items (the full desired state to render config from)
  netautomate.netorca.netorca_service_item_info:
    service_name: [LOAD_BALANCER]
    runtime_state: [IN_SERVICE]
    ordering: -created
  register: lb_items

- name: Load balancers declared in the prod partition
  netautomate.netorca.netorca_service_item_info:
    service_name: [LOAD_BALANCER]
    declaration:
      partition: prod
  register: prod_lbs

- name: Items with approved changes waiting to be deployed
  netautomate.netorca.netorca_service_item_info:
    change_state: [CHANGES_APPROVED]
  register: has_work

- name: Get one service item by ID
  netautomate.netorca.netorca_service_item_info:
    id: 1234
  register: item

- name: Items my consumers depend on (dependant view), as a consumer
  netautomate.netorca.netorca_service_item_info:
    context: consumer
    dependant: true
  register: dependant_items

Return values

count

Number of returned service items.

• Returned: always
• Type: int
• Sample:

2

service_items

List of matching service items as returned by the NetOrca API.

• Returned: always
• Type: list / elements=dict
• Sample:

[
  {
    "application": {
      "id": 7,
      "name": "application1"
    },
    "change_state": "ALL_CHANGES_COMPLETED",
    "declaration": {
      "name": "load_balancer1",
      "partition": "prod",
      "virtual_server": {
        "ip": "10.1.10.152",
        "port": 80
      }
    },
    "id": 1234,
    "name": "load_balancer1",
    "runtime_state": "IN_SERVICE",
    "service": {
      "id": 12,
      "name": "LOAD_BALANCER"
    }
  }
]

See also

• netautomate.netorca.netorca_change_instance_info - Query the change instances (requested work) on service items.
• netautomate.netorca.netorca_deployed_item - Record what was actually deployed to fulfil a service item.

Authors

• NetAutomate (@netautomate)