Metadata-Version: 1.2
Name: ceilometer-instance-poller
Version: 1.1.2
Summary: Poll instance operating system
Home-page: UNKNOWN
Author: OpenStack
Author-email: openstack-discuss@lists.openstack.org
License: UNKNOWN
Description: # Table of Contents
        
        - [What is ceilometer-instance-poller](#what-is-ceilometer-instance-poller)
          * [General description](#general-description)
          * [Values being polled](#values-being-polled)
          * [What for](#what-for)
        - [How to setup](#how-to-setup)
          * [Requires ceilometer patches](#requires-ceilometer-patches)
          * [Configuring ceilometer on the compute nodes](#configuring-ceilometer-on-the-compute-nodes)
          * [Sending metadata to Gnocchi](#sending-metadata-to-Gnocchi)
          * [Altering attributes in Gnocchi](#altering-attributes-in-gnocchi)
          * [Cloudkitty](#cloudkitty)
        
        # What is ceilometer-instance-poller
        
        ### General description
        
        This Python package uses libvirt and libguestfs to poll data otherwise not
        available through a standard Ceilometer installation on a compute node.
        /usr/bin/ceilometer-instance-poller produces a json output that can be
        used by Ceilometer as a compute dynamic pollster.
        
        This relies on this patch being merged:
        
        https://review.opendev.org/c/openstack/ceilometer/+/852021
        
        At the time of writing, this patch is available in Debian from the
        Victoria release, but in other distributions, it may only appear
        after Antelope.
        
        ### Values being polled
        
        All the metadata needed to bill OS licenses of your running VMs.
        
        Example output:
        
        ```
        [
          {
            "resource_id": "190f5907-fd86-4ade-9315-705e14aa63cd",
            "vcpus": 4
            "os_family": "windows",
            "os_distro": "windows",
            "os_info": "win2k16",
            "os_version_major": 10,
            "os_version_minor": 0,
            "os_product_name": "Windows Server 2022 Datacenter Evaluation",
            "os_product_variant": "Server"
          },
          {
            "resource_id": "9e92c509-0b48-43d0-a552-42de6f001e36",
            "vcpus": 1
            "os_family": "linux",
            "os_distro": "debian",
            "os_info": "debian11",
            "os_version_major": 11,
            "os_version_minor": 2,
            "os_product_name": "11.2",
            "os_product_variant": "unknown"
          }
        ]
        ```
        
        ### What for
        
        Some operating systems aren't free, and needs to be charged.
        Though if booted from volume, there's no way to know what the
        base image was, and if your customer is running Windows. That's
        what this script does: it looks into the running VMs using
        read-only libguestfs to know if your customer needs to be
        charged for using a Windows license.
        
        # How to setup
        ## Requires ceilometer patches
        
        tl;dr: Only OpenStack Antelope has all the Ceilometer patches,
        otherwise you will need backports.
        
        Depending on the version of Ceilometer running in the OpenStack
        deployment where you need ceilometer-instance-poller, you may
        need some extra Ceilometer patches, backported to your version
        of OpenStack. The Debian team already maintains versions of these
        patches backported to all versions of Ceilometer from Victoria
        to Zed. A full list of these patches is available over here:
        
        https://salsa.debian.org/openstack-team/services/ceilometer/-/tree/debian/victoria/debian/patches
        
        So, basically:
        - Introduce_timeout_in_dynamic_pollsters_sub-system.patch
        - OpenStack_Dynamic_pollsters_metadata_enrichment_with_other_OpenStack_APIs_data.patch
        - Add_response_handlers_to_support_different_response_types.patch
        - Add_support_to_namespaces_on_dynamic_pollsters.patch
        - Add_support_to_host_command_dynamic_pollster_definitions.patch
        
        ## Configuring ceilometer on the compute nodes
        
        The new pollster must be in the folder `/etc/ceilometer/pollsters.d` and its
        name must be referenced in `/etc/ceilometer/polling.yaml`. Here's an example
        `ceilometer_instance_poller.yaml` configuration in the `pollsters.d`:
        
        ```
        ---
        - name: "compute.instance.os.metadata"
          sample_type: "gauge"
          unit: "vcpu"
          value_attribute: "vcpus"
          resource_id_attribute: "resource_id"
          host_command: "sudo /usr/bin/ceilometer-instance-poller --config-file /etc/ceilometer-instance-poller/ceilometer-instance-poller.conf"
          namespaces: "compute"
          metadata_fields:
            - "os_family"
            - "os_distro"
            - "os_info"
            - "os_product_name"
            - "os_product_variant"
            - "os_version_major"
            - "os_version_minor"
          response_handlers:
            - json
        ```
        
        Here we retreive vcpus number for per-cpu licencing model. You may replace 'value_attribute' by another field and use 'metadata_mapping' / 'default_value' if you prefer a different binding. 
        
        ## Sending metadata to Gnocchi
        
        It's not needed to send all of the metadata, one may decide to send only the
        feilds they need. For example, in `/etc/ceilometer/gnocchi_resources.yaml`:
        
        ```
        ...
          - resource_type: instance
            metrics:
            attributes:
              os_family: resource_metadata.os_family
              os_distro: resource_metadata.os_distro
              os_info: resource_metadata.os_info
        ```
        
        ## Altering attributes in Gnocchi
        
        ```
        $ openstack metric resource-type update instance -a os_family:string:false:max_length=255
        $ openstack metric resource-type update instance -a os_distro:string:false:max_length=255
        $ openstack metric resource-type update instance -a os_info:string:false:max_length=255
        ```
        
        ## Cloudkitty
        
        Here's a `metrics.yaml` that matches the above:
        
        ```
          compute.instance.os.metadata:
            unit: instance
            alt_name: software_licence
            groupby:
              - project_id
            metadata:
              - os_family
              - os_distro
              - os_info
            extra_args:
              aggregation_method: mean
              resource_type: instance
              force_granularity: 3600
        ```
        
        After restarting the services, we normally see the metric under alt_name : software_licence.
        
        ```
        $ openstack rating info metric get software_licence
        +------------------+----------+---------------------------------------+
        | Metric           | Unit     | Metadata                              |
        +------------------+----------+---------------------------------------+
        | software_licence | instance | ['os_distro', 'os_family', 'os_info'] |
        +------------------+----------+---------------------------------------+
        ```
        
        Then let's add a new Cloudkitty group:
        
        ```
        $ openstack rating hashmap group create software_licences
        +-------------------+--------------------------------------+
        | Name              | Group ID                             |
        +-------------------+--------------------------------------+
        | software_licences | e3d5ba8b-86af-4403-86fa-1a540295c68a |
        +-------------------+--------------------------------------+
        ```
        
        Then the service. It must have the same name as the (renamed) metric: software_licence.
        
        ```
        $ openstack rating hashmap service create software_licence
        +------------------+--------------------------------------+
        | Name             | Service ID                           |
        +------------------+--------------------------------------+
        | software_licence | 89ce2fe5-ab99-4818-a4ea-040ab9e5d20c |
        +------------------+--------------------------------------+
        ```
        
        We then add new fields:
        
        ```
        $ openstack rating hashmap field create 89ce2fe5-ab99-4818-a4ea-040ab9e5d20c os_family
        $ openstack rating hashmap field create 89ce2fe5-ab99-4818-a4ea-040ab9e5d20c os_info
        $ openstack rating hashmap field create 89ce2fe5-ab99-4818-a4ea-040ab9e5d20c os_distro
        $ openstack rating hashmap field list 89ce2fe5-ab99-4818-a4ea-040ab9e5d20c
        +-----------+--------------------------------------+--------------------------------------+
        | Name      | Field ID                             | Service ID                           |
        +-----------+--------------------------------------+--------------------------------------+
        | os_distro | 21a40fe1-f896-4540-b484-0b7bd5f414ab | 89ce2fe5-ab99-4818-a4ea-040ab9e5d20c |
        | os_info   | 23ddbff4-a8fe-4e1a-9526-c8bac8e13641 | 89ce2fe5-ab99-4818-a4ea-040ab9e5d20c |
        | os_family | 5140ebd2-b071-41b9-81f3-2c69184bc45a | 89ce2fe5-ab99-4818-a4ea-040ab9e5d20c |
        +-----------+--------------------------------------+--------------------------------------+
        ```
        
        And a new mapping:
        
        ```
        $ openstack rating hashmap mapping create --group-id e3d5ba8b-86af-4403-86fa-1a540295c68a --field-id 23ddbff4-a8fe-4e1a-9526-c8bac8e13641 -t flat --value win2k16 0.5
        +--------------------------------------+---------+------------+------+--------------------------------------+------------+--------------------------------------+------------+
        | Mapping ID                           | Value   | Cost       | Type | Field ID                             | Service ID | Group ID                             | Project ID |
        +--------------------------------------+---------+------------+------+--------------------------------------+------------+--------------------------------------+------------+
        | d0e7877a-256f-4566-9f3c-6356b1edc987 | win2k16 | 0.05000000 | flat | 23ddbff4-a8fe-4e1a-9526-c8bac8e13641 | None       | e3d5ba8b-86af-4403-86fa-1a540295c68a | None       |
        +--------------------------------------+---------+------------+------+--------------------------------------+------------+--------------------------------------+------------+
        ```
        
        
Platform: UNKNOWN
Classifier: Environment :: OpenStack
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Requires-Python: >=3.9
