diff --git a/downstream/assemblies/platform/assembly-ag-controller-backup-and-restore.adoc b/downstream/assemblies/platform/assembly-ag-controller-backup-and-restore.adoc index c81379ba50..422c9ca8c1 100644 --- a/downstream/assemblies/platform/assembly-ag-controller-backup-and-restore.adoc +++ b/downstream/assemblies/platform/assembly-ag-controller-backup-and-restore.adoc @@ -4,7 +4,7 @@ You can backup and restore your system using the {PlatformNameShort} setup playbook. -For more information, see the xref:controller-backup-restore-clustered-environments[Backup and restore clustered environments] section. +For more information, see the link:{URLControllerAdminGuide}/index#controller-backup-restore-clustered-environments[Backup and restore clustered environments] section. [NOTE] ==== diff --git a/downstream/assemblies/platform/assembly-metrics-utility.adoc b/downstream/assemblies/platform/assembly-metrics-utility.adoc index 0b604949d1..13bbb21be4 100644 --- a/downstream/assemblies/platform/assembly-metrics-utility.adoc +++ b/downstream/assemblies/platform/assembly-metrics-utility.adoc @@ -9,13 +9,13 @@ ifdef::context[:parent-context-of-metrics-utility: {context}] :context: metrics-utility -= Subscription consumption += Usage reporting with metrics-utility The {PlatformNameShort} metrics utility tool (`metrics-utility`) is a command-line utility that is installed on a system containing an instance of {ControllerName}. -When installed and configured, `metrics-utility` gathers billing-related metrics from your system and creates a consumption-based billing report. Metrics-utility is especially suited for users who have multiple managed hosts and want to use consumption-based billing. Once a report is generated, it is deposited in a target location that you specify in the configuration file. +When installed and configured, `metrics-utility` gathers billing-related metrics from your system and creates a consumption-based billing report. The `metrics-utility` tool is especially suited for users who have multiple managed hosts and want to use consumption-based billing. After a report is generated, it is deposited in a target location that you specify in the configuration file. -Metrics-utility collects two types of data from your system: configuration data and reporting data. +`metrics-utility` collects two types of data from your system: configuration data and reporting data. The configuration data includes the following information: @@ -37,9 +37,17 @@ To ensure that `metrics-utility` continues to work as configured, clear your rep include::platform/proc-configuring-the-metrics-utility.adoc[leveloffset=+1] +include::platform/proc-configure-a-config-map.adoc[leveloffset=+3] +include::platform/proc-deploy-controller.adoc[leveloffset=+3] include::platform/ref-fetching-a-monthly-report.adoc[leveloffset=+1] include::platform/proc-modifying-the-run-schedule.adoc[leveloffset=+1] - +include::platform/ref-supported-storage.adoc[leveloffset=+1] +include::platform/ref-report-types.adoc[leveloffset=+1] +include::platform/ref-renewal-guidance.adoc[leveloffset=+1] +include::platform/ref-storage-invocation.adoc[leveloffset=+2] +include::platform/ref-show-ephemeral-use.adoc[leveloffset=+3] +include::platform/ref-select-a-date-range.adoc[leveloffset=+3] +include::platform/ref-ccsp.adoc[leveloffset=+2] ifdef::parent-context[:context: {parent-context}] ifndef::parent-context[:!context:] diff --git a/downstream/modules/platform/proc-configure-a-config-map.adoc b/downstream/modules/platform/proc-configure-a-config-map.adoc new file mode 100644 index 0000000000..569ff3d770 --- /dev/null +++ b/downstream/modules/platform/proc-configure-a-config-map.adoc @@ -0,0 +1,32 @@ +[id="proc-configure-a-config-map"] + += Create a ConfigMap in the OpenShift UI YAML view + +.Procedure +. From the navigation panel, select menu:ConfigMaps[]. +. Click btn:[Create ConfigMap]. +. On the next screen, select the YAML view tab. +. In the YAML field, enter the following parameters with the appropriate variables set: ++ +---- +apiVersion: v1 +kind: ConfigMap +metadata: + name: automationcontroller-metrics-utility-configmap +data: + METRICS_UTILITY_SHIP_TARGET: directory + METRICS_UTILITY_SHIP_PATH: /metrics-utility + METRICS_UTILITY_REPORT_TYPE: CCSP + METRICS_UTILITY_PRICE_PER_NODE: '11' # in USD + METRICS_UTILITY_REPORT_SKU: MCT3752MO + METRICS_UTILITY_REPORT_SKU_DESCRIPTION: "EX: Red Hat Ansible Automation Platform, Full Support (1 Managed Node, Dedicated, Monthly)" + METRICS_UTILITY_REPORT_H1_HEADING: "CCSP Reporting : ANSIBLE Consumption" + METRICS_UTILITY_REPORT_COMPANY_NAME: "Company Name" + METRICS_UTILITY_REPORT_EMAIL: "email@email.com" + METRICS_UTILITY_REPORT_RHN_LOGIN: "test_login" + METRICS_UTILITY_REPORT_COMPANY_BUSINESS_LEADER: "BUSINESS LEADER" + METRICS_UTILITY_REPORT_COMPANY_PROCUREMENT_LEADER: "PROCUREMENT LEADER" +---- ++ +. Click btn:[Create]. +. To verify that the ConfigMap was created and the `metrics-utility` is installed, from the navigation panel, select menu:ConfigMap[] and look for your ConfigMap in the list. diff --git a/downstream/modules/platform/proc-configuring-the-metrics-utility.adoc b/downstream/modules/platform/proc-configuring-the-metrics-utility.adoc index 30f295f415..300093408c 100644 --- a/downstream/modules/platform/proc-configuring-the-metrics-utility.adoc +++ b/downstream/modules/platform/proc-configuring-the-metrics-utility.adoc @@ -49,7 +49,7 @@ export METRICS_UTILITY_REPORT_COMPANY_BUSINESS_LEADER="BUSINESS LEADER" export METRICS_UTILITY_REPORT_COMPANY_PROCUREMENT_LEADER="PROCUREMENT LEADER" ---- + -. Add the following parameter to gather and store the data in the provided SHIP_PATH directory in the `./report_data` subdirectory: +. Run the following command to gather and store the data in the provided `SHIP_PATH` directory: + [source, ] ---- diff --git a/downstream/modules/platform/proc-deploy-controller.adoc b/downstream/modules/platform/proc-deploy-controller.adoc new file mode 100644 index 0000000000..0726bf1a3c --- /dev/null +++ b/downstream/modules/platform/proc-deploy-controller.adoc @@ -0,0 +1,26 @@ +[id="proc-deploy-controller"] + += Deploy {ControllerName} + +Deploy {ControllerName} and specify variables for how often `metrics-utility` gathers usage information and generates a report. + +. From the navigation panel, select *Installed Operators*. +. Select {PlatformNameShort}. +. In the Operator details, select the {ControllerName} tab. +. Click btn:[Create automation controller]. +. Select the YAML view option. +The YAML now shows the default parameters for {ControllerName}. +The relevant parameters for `metrics-utility` are the following: ++ +[cols="50%,50%",options="header"] +|==== +| *Parameter* | *Variable* +| *`metrics_utility_enabled`* | True. +| *`metrics_utility_cronjob_gather_schedule`* | `@hourly` or `@daily`. +| *`metrics_utility_cronjob_report_schedule`* | `@daily` or `@monthly`. +|==== ++ +. Find the `metrics_utility_enabled` parameter and change the variable to true. +. Find the `metrics_utility_cronjob_gather_schedule` parameter and enter a variable for how often the utility should gather usage information (for example, `@hourly` or `@daily`). +. Find the `metrics_utility_cronjob_report_schedule` parameter and enter a variable for how often the utility generates a report (for example, `@daily` or `@monthly`). +. Click btn:[Create]. \ No newline at end of file diff --git a/downstream/modules/platform/proc-modifying-the-run-schedule.adoc b/downstream/modules/platform/proc-modifying-the-run-schedule.adoc index 2dd04fd9d8..d81066709d 100644 --- a/downstream/modules/platform/proc-modifying-the-run-schedule.adoc +++ b/downstream/modules/platform/proc-modifying-the-run-schedule.adoc @@ -8,7 +8,8 @@ You can configure `metrics-utility` to run at specified times and intervals. Run frequency is expressed in cronjobs. See link:https://www.redhat.com/sysadmin/linux-cron-command[How to schedule jobs using the Linux ‘Cron’ utility] for more information. -== On RHEL +== On {RHEL} + .Procedure . From the command line, run: @@ -23,19 +24,20 @@ crontab -e [source, ] ---- */2 * * * * metrics-utility gather_automation_controller_billing_data --ship --until=10m -*/5 * * * * metrics-utili -ty build_report +*/5 * * * * metrics-utility build_report ---- + . Save and close the file. == On {OCPShort} from the {PlatformNameShort} operator + .Procedure . From the navigation panel, select menu:Workloads[Deployments]. . On the next screen, select *automation-controller-operator-controller-manager*. -. Beneath the heading *Deployment Details*, click the down arrow button to change the number of pods to zero. This will pause the deployment so you can update the running schedule. -. From the navigation panel, select *Installed Operators*. From the list of installed operators, select {PlatformNameShort}. +. Beneath the heading *Deployment Details*, click the down arrow button to change the number of pods to zero. This pauses the deployment so you can update the running schedule. +. From the navigation panel, select *Installed Operators*. +. From the list of installed operators, select {PlatformNameShort}. . On the next screen, select the {ControllerName} tab. . From the list that appears, select your {ControllerName} instance. . On the next screen, select the `YAML` tab. @@ -53,3 +55,4 @@ metrics_utility_cronjob_report_schedule: . To verify that you have changed the `metrics-utility` running schedule successfully, you can take one or both of the following steps: .. return to the `YAML` file and ensure that the parameters described above reflect the correct variables. .. From the navigation menu, select menu:Workloads[Cronjobs] and ensure that your cronjobs show the updated schedule. + diff --git a/downstream/modules/platform/ref-ccsp.adoc b/downstream/modules/platform/ref-ccsp.adoc new file mode 100644 index 0000000000..eba3ecb417 --- /dev/null +++ b/downstream/modules/platform/ref-ccsp.adoc @@ -0,0 +1,76 @@ +[id="ref-ccsp"] + += CCSP + +`CCSP` is the original report format. It does not include many of the customization of CCSPv2, and it is intended to be used only for the CCSP partner program. + +== Optional collectors for `gather` command + +You can use the following optional collectors for the `gather` command: + +* `main_jobhostsummary` +** If present by default, this incrementally collects the `main_jobhostsummary` table from the {ControllerName} database, containing information about jobs runs and managed nodes automated. +* `main_host` +** This collects daily snapshots of the `main_host` table from the {ControllerName} database and has managed nodes/hosts present across {ControllerName} inventories, +* `main_jobevent` +** This incrementally collects the `main_jobevent` table from the {ControllerName} database and contains information about which modules, roles, and ansible collections are being used. +* main_indirectmanagednodeaudit +** This incrementally collects the `main_indirectmanagednodeaudit` table from the {ControllerName} database and contains information about indirectly managed nodes, + +---- +# Example with all optional collectors +export METRICS_UTILITY_OPTIONAL_COLLECTORS="main_host,main_jobevent,main_indirectmanagednodeaudit" +---- + +== Optional sheets for `build_report` command + +You may use the following optional sheets for the `build_report` command: + +* `ccsp_summary` +** This is a landing page specifically for partners under the CCSP program. It shows managed node usage by each {ControllerName} organization. +** This report takes additional parameters to customize the summary page. For more information, see the following example: + +---- +export METRICS_UTILITY_PRICE_PER_NODE=11.55 # in USD +export METRICS_UTILITY_REPORT_SKU=MCT3752MO +export METRICS_UTILITY_REPORT_SKU_DESCRIPTION="EX: Red Hat Ansible Automation Platform, Full Support (1 Managed Node, Dedicated, Monthly)" +export METRICS_UTILITY_REPORT_H1_HEADING="CCSP Reporting : ANSIBLE Consumption" +export METRICS_UTILITY_REPORT_COMPANY_NAME="Company Name" +export METRICS_UTILITY_REPORT_EMAIL="email@email.com" +export METRICS_UTILITY_REPORT_RHN_LOGIN="test_login" +export METRICS_UTILITY_REPORT_COMPANY_BUSINESS_LEADER="BUSINESS LEADER" +export METRICS_UTILITY_REPORT_COMPANY_PROCUREMENT_LEADER="PROCUREMENT LEADER" +---- + +* `managed_nodes` +** This is a deduplicated list of managed nodes automated by {ControllerName}. +* `indirectly_managed_nodes` +** This is a deduplicated list of indirect managed nodes automated by {ControllerName}. +* `inventory_scope` +** This is a deduplicated list of managed nodes present across all inventories of {ControllerName}. +* `usage_by_collections` +** This is a list of Ansible collections used in {ControllerName} job runs. +* `usage_by_roles` +** This is a list of roles used in {ControllerName} job runs. +*`usage_by_modules` +** This is a list of modules used in {ControllerName}job runs. + +---- +# Example with all optional sheets +export METRICS_UTILITY_OPTIONAL_CCSP_REPORT_SHEETS='ccsp_summary,managed_nodes,indirectly_managed_nodes,inventory_scope,usage_by_collections,usage_by_roles,usage_by_modules' +---- + +== Selecting a date range for your CCSP report + +The default behavior of this report is to build a report for the previous month. The following examples describe how to override this default behavior to select a specific date range for your report: + +---- +# Builds report for a previous month +metrics-utility build_report + +# Build report for a specific month +metrics-utility build_report --month=2025-03 + +# Build report for a specific month overriding an existing report +metrics-utility build_report --month=2025-03 --force +---- \ No newline at end of file diff --git a/downstream/modules/platform/ref-configuring-metrics-utility.adoc b/downstream/modules/platform/ref-configuring-metrics-utility.adoc new file mode 100644 index 0000000000..d87300b5e5 --- /dev/null +++ b/downstream/modules/platform/ref-configuring-metrics-utility.adoc @@ -0,0 +1,133 @@ +:_newdoc-version: 2.18.3 +:_template-generated: 2024-07-15 + +:_mod-docs-content-type: REFERENCE + +[id="ref-configuring-metrics-utility_{context}"] += Configuring metrics-utility + +== On {RHEL} + +.Prerequisites + +* An active {PlatformName} subscription +* An existing installation of {PlatformName} on {RHEL} + +`metrics-utility` is included with {PlatformName}, so you do not need a separate installation. The following commands gather the relevant data and generate a link:https://connect.redhat.com/en/programs/certified-cloud-service-provider[CCSP] report containing your usage metrics. +You can configure these commands as cron jobs to ensure they run at the beginning of every month. See link:https://www.redhat.com/en/blog/linux-cron-command[How to schedule jobs using the Linux 'cron' utility] for more on configuring using the cron syntax. + +.Procedure +. In the `cron` file, set the correct variables to ensure `metrics-utility` gathers the relevant data. To open the cron file for editing, run: ++ +`crontab -e` + +. Specify the following variables to indicate where the report is deposited in your file system: ++ +---- +export METRICS_UTILITY_SHIP_TARGET=directory +export METRICS_UTILITY_SHIP_PATH=/awx_devel/awx-dev/metrics-utility/shipped_data/billing +---- +. Set these variables to generate a report: ++ +---- +export METRICS_UTILITY_REPORT_TYPE=CCSP +export METRICS_UTILITY_PRICE_PER_NODE=11.55 # in USD +export METRICS_UTILITY_REPORT_SKU=MCT3752MO +export METRICS_UTILITY_REPORT_SKU_DESCRIPTION="EX: Red Hat Ansible Automation Platform, Full Support (1 Managed Node, Dedicated, Monthly)" +export METRICS_UTILITY_REPORT_H1_HEADING="CCSP Reporting : ANSIBLE Consumption" +export METRICS_UTILITY_REPORT_COMPANY_NAME="Company Name" +export METRICS_UTILITY_REPORT_EMAIL="email@email.com" +export METRICS_UTILITY_REPORT_RHN_LOGIN="test_login" +export METRICS_UTILITY_REPORT_COMPANY_BUSINESS_LEADER="BUSINESS LEADER" +export METRICS_UTILITY_REPORT_COMPANY_PROCUREMENT_LEADER="PROCUREMENT LEADER" +---- + +. Run the following command to gather and store the data in the provided `SHIP_PATH` directory: ++ +`metrics-utility gather_automation_controller_billing_data --ship --until=10m` + +. To configure the run schedule, add the following parameters to the end of the file and specify how often you want `metrics-utility` to gather information and build a report using link:https://www.redhat.com/en/blog/linux-cron-command[cron syntax]. +In the following example, the `gather` command is configured to run every hour at 00 minutes. The `build_report` command is configured to run every second day of each month at 4:00 AM. ++ +---- +0 */1 * * * metrics-utility gather_automation_controller_billing_data --ship --until=10m +0 4 2 * * metrics-utility build_report +---- + +. Save and close the file. +. To verify that you saved your changes, run: ++ +`crontab -l` + +. You can also check the logs to ensure that data is being collected. Run: ++ +`cat /var/log/cron` + +. The following is an example of the output. Note that time and date might vary depending on how your configure the run schedule: ++ +---- +May 8 09:45:03 ip-10-0-6-24 CROND[51623]: (root) CMDOUT (No billing data for month: 2024-04) +May 8 09:45:03 ip-10-0-6-24 CROND[51623]: (root) CMDEND (metrics-utility build_report) +May 8 09:45:19 ip-10-0-6-24 crontab[51619]: (root) END EDIT (root) +May 8 09:45:34 ip-10-0-6-24 crontab[51659]: (root) BEGIN EDIT (root) +May 8 09:46:01 ip-10-0-6-24 CROND[51688]: (root) CMD (metrics-utility gather_automation_controller_billing_data --ship --until=10m) +May 8 09:46:03 ip-10-0-6-24 CROND[51669]: (root) CMDOUT (/tmp/9e3f86ee-c92e-4b05-8217-72c496e6ffd9-2024-05-08-093402+0000-2024-05-08-093602+0000-0.tar.gz) +May 8 09:46:03 ip-10-0-6-24 CROND[51669]: (root) CMDEND (metrics-utility gather_automation_controller_billing_data --ship --until=10m) +May 8 09:46:26 ip-10-0-6-24 crontab[51659]: (root) END EDIT (root) +---- + +. Run the following command to build a report for the previous month: ++ +`metrics-utility build_report` + +. The system saves the generated report as `CCSP--.xlsx` in the ship path that you specified in step 2. + + +== On {OCPShort} from the {PlatformNameShort} operator + +`metrics-utility` is included in the {OCPShort} image beginning with version 4.12. +If your system does not have `metrics-utility` installed, update your OpenShift image to the latest version. +Follow the steps below to configure the run schedule for `metrics-utility` on {OCPShort} using the {PlatformName} Operator. + +. Prerequisites: + +* A running OpenShift cluster +* An operator-based installation of {PlatformNameShort} on {OCPShort}. ++ +[Note] +==== +`metrics-utility` runs as indicated by the parameters you set in the configuration file. +The utility cannot be run manually on {OCPShort}. +==== + +== Create a ConfigMap in the OpenShift UI YAML view + +.Procedure +. From the navigation panel, select menu::ConfigMaps[]. +. Click btn:[Create ConfigMap]. +. On the next screen, select the YAML view tab. +. In the YAML field, enter the following parameters with the appropriate variables set: ++ +---- +apiVersion: v1 +kind: ConfigMap +metadata: + name: automationcontroller-metrics-utility-configmap +data: + METRICS_UTILITY_SHIP_TARGET: directory + METRICS_UTILITY_SHIP_PATH: /metrics-utility + METRICS_UTILITY_REPORT_TYPE: CCSP + METRICS_UTILITY_PRICE_PER_NODE: '11' # in USD + METRICS_UTILITY_REPORT_SKU: MCT3752MO + METRICS_UTILITY_REPORT_SKU_DESCRIPTION: "EX: Red Hat Ansible Automation Platform, Full Support (1 Managed Node, Dedicated, Monthly)" + METRICS_UTILITY_REPORT_H1_HEADING: "CCSP Reporting : ANSIBLE Consumption" + METRICS_UTILITY_REPORT_COMPANY_NAME: "Company Name" + METRICS_UTILITY_REPORT_EMAIL: "email@email.com" + METRICS_UTILITY_REPORT_RHN_LOGIN: "test_login" + METRICS_UTILITY_REPORT_COMPANY_BUSINESS_LEADER: "BUSINESS LEADER" + METRICS_UTILITY_REPORT_COMPANY_PROCUREMENT_LEADER: "PROCUREMENT LEADER" +---- + +. Click btn:[Create]. + +. To verify that the ConfigMap was created and `metrics-utility` is installed, select menu::ConfigMap[] from the navigation panel and look for your ConfigMap in the list. \ No newline at end of file diff --git a/downstream/modules/platform/ref-controller-cluster-instance-behavior.adoc b/downstream/modules/platform/ref-controller-cluster-instance-behavior.adoc index 7f026b2ee5..fed756c5ab 100644 --- a/downstream/modules/platform/ref-controller-cluster-instance-behavior.adoc +++ b/downstream/modules/platform/ref-controller-cluster-instance-behavior.adoc @@ -13,4 +13,4 @@ Rsyslog:: The log processing service used to deliver logs to various external lo {ControllerNameStart} is configured so that if any of these services or their components fail, then all services are restarted. If these fail often in a short span of time, then the entire instance is placed offline in an automated fashion to allow remediation without causing unexpected behavior. -For backing up and restoring a clustered environment, see the xref:controller-backup-restore-clustered-environments[Backup and restore clustered environments] section. +For backing up and restoring a clustered environment, see the link:{URLControllerAdminGuide}/index#controller-backup-restore-clustered-environments[Backup and restore clustered environments] section. diff --git a/downstream/modules/platform/ref-fetching-a-monthly-report.adoc b/downstream/modules/platform/ref-fetching-a-monthly-report.adoc index cbc7241e44..c855278b75 100644 --- a/downstream/modules/platform/ref-fetching-a-monthly-report.adoc +++ b/downstream/modules/platform/ref-fetching-a-monthly-report.adoc @@ -1,27 +1,19 @@ -:_newdoc-version: 2.18.3 -:_template-generated: 2024-07-15 +[id="ref-fetching-a-monthly-report"] -:_mod-docs-content-type: REFERENCE += Fetching a monthly report -[id="fetching-a-monthly-report_{context}"] -= Fetching a monthly report +== On {RHEL} +To fetch a monthly report on RHEL, run: -== On RHEL -To fetch a monthly report on RHEL, run: +`scp -r username@controller_host:$METRICS_UTILITY_SHIP_PATH/data/// /local/directory/` -[source, ] ----- -scp -r username@controller_host:$METRICS_UTILITY_SHIP_PATH/data/// /local/directory/ ----- +The system savess the generated report as `CCSP--.xlsx` in the ship path that you specified. -The generated report will have the default name CCSP--.xlsx and will be deposited in the ship path that you specified. - -== On {OCPShort} from the {PlatformNameShort} operator +== On {OCPShort} from the {PlatformNameShort} Operator Use the following playbook to fetch a monthly consumption report for {PlatformNameShort} on {OCPShort}: -[source, ] ---- - name: Copy directory from Kubernetes PVC to local machine hosts: localhost @@ -104,3 +96,4 @@ Use the following playbook to fetch a monthly consumption report for {PlatformNa name: temp-pod state: absent ---- + diff --git a/downstream/modules/platform/ref-renewal-guidance.adoc b/downstream/modules/platform/ref-renewal-guidance.adoc new file mode 100644 index 0000000000..e4ab2ddb20 --- /dev/null +++ b/downstream/modules/platform/ref-renewal-guidance.adoc @@ -0,0 +1,12 @@ +[id="ref-renewal-guidance"] + += `RENEWAL_GUIDANCE` +The `RENEWAL_GUIDANCE` report provides historical usage from the HostMetric table, applying deduplication and showing real historical usage for renewal guidance purposes. + +To generate this report, set the report type to +`METRICS_UTILITY_REPORT_TYPE=RENEWAL_GUIDANCE`. + +[IMPORTANT] +==== +This report is currently a tech preview solution. It is designed to provide more information than {ControllerName} when built in the `awx-manage host_metric` command. +==== diff --git a/downstream/modules/platform/ref-report-types.adoc b/downstream/modules/platform/ref-report-types.adoc new file mode 100644 index 0000000000..d4aa4595cf --- /dev/null +++ b/downstream/modules/platform/ref-report-types.adoc @@ -0,0 +1,98 @@ +[id="ref-report-types"] + += Report types +This section provides additional configurations for data gathering and report building based on a report type. Apply the environment variables to each report type based on your {PlatformNameShort} installation. + +== CCSPv2 + +CCSPv2 is a report which shows the following: + +* Directly and indirectly managed node usage +* The content of all inventories +* Content usage + +The primary use of this report is for partners under the link:https://connect.redhat.com/en/programs/certified-cloud-service-provider[CCSP] program, but all customers can use it to obtain on-premise reporting showing managed nodes, jobs and content usage across their {ControllerName} organizations. + +Set the report type using `METRICS_UTILITY_REPORT_TYPE=CCSPv2`. + +=== Optional collectors for `gather` command + +You can use the following optional collectors for the `gather` command: + +* `main_jobhostsummary` +** If present by default, this incrementally collects data from the `main_jobhostsummary` table in the {ControllerName} database, containing information about jobs runs and managed nodes automated. +* `main_host` +** This collects daily snapshots of the `main_host` table in the {ControllerName} database and has managed nodes and hosts present across {ControllerName} inventories. +* `main_jobevent` +** This incrementally collects data from the `main_jobevent` table in the {ControllerName} database and contains information about which modules, roles, and Ansible collections are being used. +* `main_indirectmanagednodeaudit` +** This incrementally collects data from the `main_indirectmanagednodeaudit` table in the {ControllerName} database and contains information about indirectly managed nodes. + +---- +# Example with all optional collectors +export METRICS_UTILITY_OPTIONAL_COLLECTORS="main_host,main_jobevent,main_indirectmanagednodeaudit" +---- + +=== Optional sheets for `build_report` command + +You can use the following optional sheets for the `build_report` command: + +* `ccsp_summary` +** This is a landing page specifically for partners under CCSP program. +This report takes additional parameters to customize the summary page. For more information, see the following example: ++ +---- +export METRICS_UTILITY_PRICE_PER_NODE=11.55 # in USD +export METRICS_UTILITY_REPORT_SKU=MCT3752MO +export METRICS_UTILITY_REPORT_SKU_DESCRIPTION="EX: Red Hat Ansible Automation Platform, Full Support (1 Managed Node, Dedicated, Monthly)" +export METRICS_UTILITY_REPORT_H1_HEADING="CCSP NA Direct Reporting Template" +export METRICS_UTILITY_REPORT_COMPANY_NAME="Partner A" +export METRICS_UTILITY_REPORT_EMAIL="email@email.com" +export METRICS_UTILITY_REPORT_RHN_LOGIN="test_login" +export METRICS_UTILITY_REPORT_PO_NUMBER="123" +export METRICS_UTILITY_REPORT_END_USER_COMPANY_NAME="Customer A" +export METRICS_UTILITY_REPORT_END_USER_CITY="Springfield" +export METRICS_UTILITY_REPORT_END_USER_STATE="TX" +export METRICS_UTILITY_REPORT_END_USER_COUNTRY="US" +---- +* `jobs` +** This is a list of {ControllerName} jobs launched. It is grouped by job template. +* `managed_nodes` +** This is a deduplicated list of managed nodes automated by {ControllerName}. +* `indirectly_managed_nodes` +** This is a deduplicated list of indirect managed nodes automated by {ControllerName}. +* `inventory_scope` +** This is a deduplicated list of managed nodes present across all inventories of {ControllerName}. +* `usage_by_organizations` +** This is a list of all {ControllerName} organizations with several metrics showing the organizations usage. This provides data suitable for doing internal chargeback. +* `usage_by_collections` +** This is a list of Ansible collections used in a{ControllerName} job runs. +* `usage_by_roles` +** This is a list of roles used in {ControllerName} job runs. +* `usage_by_modules` +** This is a list of modules used in {ControllerName} job runs. +* `managed_nodes_by_organization` +** This generates a sheet per organization, listing managed nodes for every organization with the same content as the managed_nodes sheet. +* `data_collection_status` +** This generates a sheet with the status of every data collection done by the `gather` command for the date range the report is built for. + +To outline the quality of data collected it also lists: + +*** unusual gaps between collections (based on collection_start_timestamp) +*** gaps in collected intervals (based on since vs until) ++ +---- +# Example with all optional sheets +export METRICS_UTILITY_OPTIONAL_CCSP_REPORT_SHEETS='ccsp_summary,jobs,managed_nodes,indirectly_managed_nodes,inventory_scope,usage_by_organizations,usage_by_collections,usage_by_roles,usage_by_modules,data_collection_status' +---- + +== Filtering reports by organization +To filter your report so that only certain organizations are present, use this environment variable with a semicolon separated list of organization names. + +`export METRICS_UTILITY_ORGANIZATION_FILTER="ACME;Organization 1"` + +This renders only the data from these organizations in the built report. This filter currently does not have any effect on the following optional sheets: + +* `usage_by_collections` +* `usage_by_roles` +* `usage_by_modules`. \ No newline at end of file diff --git a/downstream/modules/platform/ref-select-a-date-range.adoc b/downstream/modules/platform/ref-select-a-date-range.adoc new file mode 100644 index 0000000000..c35a18b47f --- /dev/null +++ b/downstream/modules/platform/ref-select-a-date-range.adoc @@ -0,0 +1,16 @@ +[id="ref-select-a-date-range"] + += Selecting a date range for your `RENEWAL_GUIDANCE` report + +The `RENEWAL_GUIDANCE` report requires a `since` parameter as the parameter is not supported due to the nature of the HostMetric data and is always set to `now`. To override a report date range that has already been built, use parameter `–force` with the command. For more information, see the following examples: + +---- +# Build report for a specific date range, including the provided days +metrics-utility build_report --since=2025-03-01 + +# Build report for a last 12 months from a current date +metrics-utility build_report --since=12months + +# Build report for a last 12 months from a current date overriding an existing report +metrics-utility build_report --since=12months --force +---- \ No newline at end of file diff --git a/downstream/modules/platform/ref-show-ephemeral-use.adoc b/downstream/modules/platform/ref-show-ephemeral-use.adoc new file mode 100644 index 0000000000..a2fad32457 --- /dev/null +++ b/downstream/modules/platform/ref-show-ephemeral-use.adoc @@ -0,0 +1,11 @@ +[id="ref-show-ephemeral-use"] + += Showing ephemeral usage + +The `RENEWAL_GUIDANCE` report has the capability to list additional sheets with ephemeral usage if the `–ephemeral` parameter is provided. Using the parameter `--ephemeral=1month`, you can define ephemeral nodes as any managed node that has been automated for a maximum of one month, then never automated again. Using this parameter, the total ephemeral usage of the 12-month period is computed as maximum ephemeral nodes used over all 1-month rolling date windows. This sheet is also added into the report. + +---- +# Will generate report for 12 months back with epehemeral nodes being nodes +# automated for less than 1 month. +metrics-utility build_report --since=12months --ephemeral=1month +---- diff --git a/downstream/modules/platform/ref-storage-invocation.adoc b/downstream/modules/platform/ref-storage-invocation.adoc new file mode 100644 index 0000000000..e4068630b5 --- /dev/null +++ b/downstream/modules/platform/ref-storage-invocation.adoc @@ -0,0 +1,15 @@ +[id="ref-storage-invocation"] + += Storage and invocation +The `RENEWAL_GUIDANCE` report supports the use of only local disk storage to store the report results. This report does not have a gather data step. It reads directly from the controller HostMetric table, so it does not store any raw data under the `METRICS_UTILITY_SHIP_PATH`. + +---- +# All parameters the RENEWAL_GUIDANCE report needs +export METRICS_UTILITY_SHIP_TARGET=controller_db +export METRICS_UTILITY_REPORT_TYPE=RENEWAL_GUIDANCE +export METRICS_UTILITY_SHIP_PATH=/path_to_built_report/... + +# Will generate report for 12 months back with epehemeral nodes being nodes +# automated for less than 1 month. +metrics-utility build_report --since=12months --ephemeral=1month +---- \ No newline at end of file diff --git a/downstream/modules/platform/ref-supported-storage.adoc b/downstream/modules/platform/ref-supported-storage.adoc new file mode 100644 index 0000000000..4481b839da --- /dev/null +++ b/downstream/modules/platform/ref-supported-storage.adoc @@ -0,0 +1,38 @@ +[id="ref-supported-storage"] + += Supported storage + +Supported storage is available for storing the raw data obtained by using the `metrics-utility gather_automation_controller_billing_data` command and storing the generated reports obtained by using the `metrics-utility build_report` command. +Apply the environment variables to this storage based on your {PlatformNameShort} installation. + +== Local disk +For an installation of {PlatformNameShort} on {RHEL}, the default storage option is a local disk. Using an OpenShift deployment of {OCPShort}, default storage is a path inside the attached Persistent Volume Claim. + +---- +# Set needed ENV VARs for gathering data and generating reports +export METRICS_UTILITY_SHIP_TARGET=directory +# Your path on the local disk +export METRICS_UTILITY_SHIP_PATH=/path_to_data_and_reports/... +---- + +== Object storage with S3 interface + +To use object storage with S3 interface, for example, with AWS S3, Ceph Object storage, or Minio, you must define environment variables for data gathering and report building commands and cronjobs. +---- +################ +export METRICS_UTILITY_SHIP_TARGET=s3 +# Your path in the object storage +export METRICS_UTILITY_SHIP_PATH=path_to_data_and_reports/... + +################ +# Define S3 config +export METRICS_UTILITY_BUCKET_NAME=metricsutilitys3 +export METRICS_UTILITY_BUCKET_ENDPOINT="https://s3.us-east-1.amazonaws.com" +# For AWS S3, define also a region +export METRICS_UTILITY_BUCKET_REGION="us-east-1" + +################ +# Define S3 credentials +export METRICS_UTILITY_BUCKET_ACCESS_KEY= +export METRICS_UTILITY_BUCKET_SECRET_KEY= +---- \ No newline at end of file