Chapter 1. Creating an OpenShift Container Platform integration 1.1. Installation tasks summary The Cost Management Metrics Operator gathers data from OpenShift Container Platform for cost management. Install the Cost Management Metrics Operator on your OpenShift Container Platform instance as part of installing cost management. When you have finished installing cost management, visit cost management to view your cost data. Operator installation, configuration, and integration management can all be performed from the OpenShift Container Platform web console. Note To install and configure Cost Management Metrics Operator from the OpenShift Container Platform web console, you must use an account with cluster administrator privileges. Prerequisites The OpenShift Container Platform cluster is installed. You can access the OpenShift Container Platform web console using an account that has cluster administrator privileges. You can access Red Hat Hybrid Cloud Console with the correct privileges for the cost management service. See, Limiting access to cost management resources for more information. Perform the following tasks to install the Cost Management Metrics Operator and begin using the cost management application in OpenShift Container Platform: Task summary Install the Cost Management Metrics Operator ( costmanagement-metrics-operator ) and use the default token authentication. Create a CostManagementMetricsConfig YAML file that configures costmanagement-metrics-operator Create a cost management OpenShift Container Platform integration with a new installation, or confirm an existing integration with a replacement installation. If you do not use token authentication, you must take additional steps to configure the secret that holds the client_id and client_secret credentials for your service account from Red Hat Hybrid Cloud Console . 1.2. Installing the cost operator by using OperatorHub Learn how to install the Cost Management Metrics Operator from the OpenShift Container Platform web console . Prerequisites You logged in to the OpenShift Container Platform web console and have cluster administrator privileges. Procedure Log in to the OpenShift Container Platform web console and click Operators OperatorHub . Click Cost Management Metrics Operator . When the Install Operator window appears, select the costmanagement-metrics-operator namespace. If the namespace does not exist, we create it for you. Click Install . After a short wait, Cost Management Metrics Operator appears in the Installed Operators tab under Project: all projects or Project: costmanagement-metrics-operator . Important If a proxy with a custom CA certificate, you must create additional configurations to inject this certificate into Cost Management Metrics Operator. For more details, see Injecting a custom CA certificate in the OpenShift Container Platform documentation. 1.3. Optional: Installing the cost management operator by using the CLI If you are automating cluster creation, you can optionally install the Cost Management Metrics Operator by using the OpenShift CLI instead of OperatorHub. In the OpenShift Container Platform CLI, you can create an integration for your OpenShift Container Platform cluster in cost management. If you use service authentication, you must configure your Operator to use it. Prerequisites You installed the OpenShift CLI, oc . You have cluster administrator privileges for your OpenShift Container Platform cluster. Procedure To verify the package manifests have the supported install modes and available channels, enter the following command: oc describe packagemanifests costmanagement-metrics-operator -n openshift-marketplace Create an OperatorGroup object and a subscription object. To create a subscription object, see the OpenShift documentation Installing from OperatorHub using the CLI . If you are not using token authentication, configure your Operator to use service account authorization. To use this method, add your service account to a User Access Group that has a Cloud Administrator role. Ensure the service account inherits the permissions of the user group. For more information, see Limiting access to cost managment resources . Retrieve your client_id and client_secret from the Red Hat Hybrid Cloud Console service account . Encode the value of your service account's client_id in base64. In your terminal, enter: echo -n "<red_hat_service_account_client_id>" | base64 Encode the value of your service account's `client_secret`in base64. In your terminal, enter: echo -n "<red_hat_service_account_client_secret>" | base64 Create a YAML file to store your secrets. Paste the client_id and client_secret in the data.client_id and data.client_secret fields. Example.yaml kind: Secret apiVersion: v1 metadata: name: service-account-auth-secret namespace: costmanagement-metrics-operator data: client_id: <base64_encoded_red_hat_service_account_client_id> client_secret: <base64_encoded_red_hat_service_account_client_secret> Deploy your secret YAML file with the following command: oc apply -f example.yaml To use service authentication for the cost management Operator, edit the custom resource definition for the Operator. You must edit the custom resource example YAML so that authentication.type is set to service-account . You must also add a line so that authentication.secret_name is set to the name of your secret. In this earlier example, the name of the secret is service-account-auth-secret . Custom resource example kind: CostManagementMetricsConfig apiVersion: costmanagement-metrics-cfg.openshift.io/v1beta1 metadata: name: costmanagementmetricscfg-sample-v1beta1 namespace: costmanagement-metrics-operator spec: authentication: type: service-account secret_name: service-account-auth-secret packaging: max_reports_to_store: 30 max_size_MB: 100 prometheus_config: collect_previous_data: true context_timeout: 120 disable_metrics_collection_cost_management: false disable_metrics_collection_resource_optimization: false source: check_cycle: 1440 create_source: false name: '' upload: upload_cycle: 360 upload_toggle: true To create an integration automatically without using the wizard in Red Hat Hybrid Cloud Console , edit the custom resource example YAML so that source.create_source is set to true and source.name is set to a name. In this example, the name is set to cluster2 . Source creation example kind: CostManagementMetricsConfig apiVersion: costmanagement-metrics-cfg.openshift.io/v1beta1 metadata: name: costmanagementmetricscfg-sample-v1beta1 namespace: costmanagement-metrics-operator spec: authentication: type: service-account secret_name: service-account-auth-secret packaging: max_reports_to_store: 30 max_size_MB: 100 prometheus_config: collect_previous_data: true context_timeout: 120 disable_metrics_collection_cost_management: false disable_metrics_collection_resource_optimization: false source: check_cycle: 1440 create_source: true name: 'cluster2' upload: upload_cycle: 360 upload_toggle: true Important If a proxy with a custom CA certificate, you must create additional configurations to inject this certificate into Cost Management Metrics Operator. For more details, see Injecting a custom CA certificate in the OpenShift Container Platform documentation. 1.4. Configuring the operator instance After you install the costmanagement-metrics-operator instance, you can configure it in the OpenShift Container Platform web console . Prerequisites You logged in to the OpenShift Container Platform web console and have cluster administrator privileges. Cost Management Metrics Operator appears in the Installed Operators tab. Procedure From Name in the list of installed operators, click Cost Management Metrics Operator . An Installed Operators Operator Details window appears. From Details , click + Create Instance . An Cost Management Metrics Operator Create CostManagementMetricsConfig window appears. Select YAML view to view and modify the contents of the YAML configuration file. Create a cost management instance for the Cost Management Metrics Operator by editing the following two lines in the YAML file: Change false to true . If you want to edit other configurations, see Configurable parameters . Change '' to the name of your integration. If you do not provide a name, the operator defaults to the cluster ID. Example Click Create . 1.5. Troubleshooting issues with your Cost Management Operator Troubleshoot problems that might occur when you install the Cost Management Operator. 1.5.1. Verify the YAML file is propery configured To verify that the cost management operator is functioning correctly, check that your YAML file is properly configured. Prerequisites You have access to the OpenShift Container Platform web console . You can view the content in the Installed Operators tab. Procedure Click the Installed Operators tab. In the list of installed operators, click Cost Management Metrics Operator .A metrics operator window opens. Click the CostManagementMetricsConfig tab to show a list of the configuration file names. In the file name list, click the configuration file that you want to verify. In the default installation, the file name is costmanagementmetricscfg-sample . A Details window opens. Click YAML and check the following items: prometheus_configured and prometheus_connected should be set to true : ingress_path , last_successful_upload_time , last_upload_status , and last_upload_time should all have content: Note To collect data, cost management uses Prometheus queries that you can find in the source code . 1.5.2. Large OpenShift deployment issues If your deployment is large, the pod might be stopped with an ``OOMkilled`` message using the default resource requests. Increase the pod memory to 2GiB or more for the initial data ingestion. After the initial data ingestion completes, pod memory can be reduced. The exact memory requirements for the pod vary based on the size of the OpenShift cluster. 1.6. Configuring service account authentication for the cost management metrics operator Important Basic authentication is no longer supported. If you manually configured the cost management metrics operator to use basic authentication, complete the following instructions to set up service account authentication. For more information, see Transition of Red Hat Hybrid Cloud Console APIs from basic authentication to token-based authentication via service accounts . 1.6.1. Creating a service account Before you can set up service account authentication for the cost management metrics operator, you must have a Client ID and Client Secret for your Red Hat Hybrid Cloud Console Service Account . If you already have this information, proceed to Creating the secret key/value pair for authentication . To create a service account and get your Client ID and Client Secret , complete the following steps: Procedure From Red Hat Hybrid Cloud Console , click Settings . Click Identity & Access Management . Click the tab Service Accounts . Click Create service account . Enter a name and description. The name must start with a letter and end with either a letter or a number. Use only alphanumeric characters and hyphens. Click Create . Copy the Client ID and Client Secret and store them in a safe location. The secret will not be showed again after you close the window. Select the checkbox I have copied the client ID and secret and then click Close . You should now see the account that you made in the list. 1.6.1.1. Granting access to the service account After you create a service account, you need to associate it with a group. Procedure Click the tab User Access and then click Groups . Find your desired group in the list and click its name. In the window that opens, click the tab Service Accounts . Click Add Service account . Select the service account that you made in the section, or whichever service account that you want to associate with the group. Click Add to group . Your service account will now inherit permissions associated with the roles in your group. To create an integration, the service account that you created for the operator needs the Cloud Administrator role. For more information, see Default user roles in cost management . 1.6.2. Configuring service account authentication Prerequisites You are logged into the OpenShift Container Platform web console and have cluster administrator privileges. The Cost Management Metrics Operator appears in the Installed Operators tab. You have a Client ID and Client Secret for your Red Hat Hybrid Cloud Console Service Account . If you do not have this information, refer to the two sections for instructions. 1.6.3. Creating the secret key/value pair for service account authentication Procedure In the OpenShift Container Platform web console, click the tab Workloads and then click Secrets . In the Secrets window, click the Create drop-down and then select Key/value secret . You will make two keys: one for your Client ID and one for your Client Secret . Enter the following information in the Create key/value secret window: Secret Name : service-account-auth-secret In Key , enter client_id . client_id In the Value field for the first key client_id` , you can upload the Value for your authorized Red Hat Hybrid Cloud Console user account, or paste it into the text box. You should have saved these credentials when you made your service account. red_hat_service_account_client_id , click Add Key/Value to add the second key/value pair, this time for your Client Secret . In Key , enter client_secret : client_secret In the Value field for the second key client_secret , you can upload the Value for your authorized Red Hat Hybrid Cloud Console user account, or paste it into the text box. red_hat_service_account_client_secret After you verify that the key/value details for the secret are correct, click Create to complete the creation of your service account authorization secret. Copy the name of your secret. You will use it in the following section. 1.6.4. Modifying the YAML file Now that you created your secret, you will modify the Cost Management Metrics Operator API YAML file. Procedure Click the tab Operators and then click Installed Operators . Find the Cost Management Metrics Operator and click its name. Click the tab Koku Metrics Config and then click the configuration file in Name . The default name is costmanagementmetricscfg-sample . Click the tab YAML to open the file. Locate the following lines in the YAML file: authentication: type: token Change type: token to type: service-account . Insert a new line for secret_name . Enter the secret that you copied in the section. Example authentication: secret_name: service-account-auth-secret #Change this line to match your secret name. type: service-account Click Save . 1.7. Manually creating an Openshift Container Platform integration You can automatically create your OpenShift Container Platform integration by following the steps in Installing a cost operator . However, some situations, such as restricted network installations, require that you create an OpenShift Container Platform integration manually on Red Hat Hybrid Cloud Console . Prerequisites You have an OpenShift Container Platform cluster installed. You are logged into the OpenShift Container Platform web console and have cluster administrator privileges. Procedure From Red Hat Hybrid Cloud Console , click Settings Menu > Integrations . Click the Red Hat tab. Click Add integration , which opens the Add a cloud integration wizard. In Select your integration type , click Red Hat OpenShift Container Platform . In Application , click cost management . Then click . Enter a name in Integration name . Then click . In a new tab, access the OpenShift Container Platform web console . Go to Home Overview and copy your Cluster Identifier . Back in cost management, enter your Cluster Identifier . Then click . Review the details and click Add to create the integration. 1.8. Updating operator resources The Cost Management Metrics Operator comes with a finite amount of resources. On larger clusters, the Cost Management Metrics Operator might run out of memory when it processes all of the metric data from Prometheus. 1.8.1. Default resources The Cost Management Metrics Operator has the following resources by default: Limits: CPU: 500m memory: 500Mi Requests: CPU: 100m memory: 20Mi 1.8.2. Increasing resources If the standard resources do not meet your needs, complete the following steps to increase the resources that are available to the operator: Go to the OpenShift Container Platform web console . From Installed Operators , click Cost Management Metrics Operator . Click the Subscription tab. Then click the Actions drop-down and select Edit Subscription . In the YAML file that appears, edit the deployment resources with values that meet the CPU and memory needs of your cluster: kind: Subscription metadata: ... spec: ... config: resources: <<<<< limits: cpu: 500m memory: 500Mi requests: cpu: 200m memory: 100Mi The operator is now redeployed and Deployment shows the new resources. For more information about .spec.config.resources , see the API documentation . 1.9. Adding a restricted network integration You can install OpenShift Container Platform on a restricted network that does not have access to the internet. The procedure to add an OpenShift Container Platform cluster operating on a restricted network as a cost management integration is different in the following ways: Operator Lifecycle Manager is configured to install and run local integrations. The costmanagement-metrics-operator is configured to store cost report CSV files locally using a persistent volume claim (PVC). Cost reports stored in the PVC are downloaded to a workstation. An OpenShift Container Platform integration is created manually. Cost reports are uploaded to Red Hat Hybrid Cloud Console from your workstation. 1.9.1. Installing the cost management operator on a restricted network Operator Lifecycle Manager (OLM) cannot access the OpenShift Container Platform clusters that are installed on restricted networks because remote integrations require full Internet connectivity. In these situations, you must install and configure OLM to run locally. Prerequisites You installed an OpenShift Container Platform cluster. You have a workstation with unrestricted network access. You logged in to the OpenShift Container Platform web console and have cluster administrator privileges. Procedure Complete the following OpenShift Container Platform procedure to create a local mirror of the costmanagement-metrics-operator : Using Operator Lifecycle Manager on restricted networks . Note The costmanagement-metrics-operator is in the redhat-operators catalog in the registry.redhat.io/redhat/redhat-operator-index:v4.11 index. Prune unwanted objects from the index before you push to the mirrored registry, but do not delete the costmanagement-metrics-operator package. Log in to the OpenShift Container Platform web console and click Operators OperatorHub . Click Cost Management Metrics Operator . The Install Operator window should open. Select the costmanagement-metrics-operator namespace that you want to install. If the namespace does not exist, it gets created. Click Install . Verification steps After a short wait, Cost Management Metrics Operator appears in the Installed Operators tab in Project: all projects or Project: costmanagement-metrics-operator . Additional resources For more details on the Operator Lifecycle Manager, see What is Operator Lifecycle Manager? 1.9.2. Configuring the Cost Operator on a restricted network Learn how to run the costmanagement-metrics-operator on a restricted network. Prerequisites You installed costmanagement-metrics-operator . You logged into the OpenShift Container Platform web console and have cluster administrator privileges. Procedure From the OpenShift Container Platform web console, select Operators > Installed Operators > costmanagement-metrics-operator > CostManagementMetricsConfig > Create Instance . Set a storage amount. If you do not specify an amount, the operator creates a default persistent volume claim (PVC) called costmanagement-metrics-operator-data with 10Gi of storage. Note To configure the costmanagement-metrics-operator to use a different PVC, edit volume_claim_template in YAML view . Select YAML view . Enter a value in max_reports_to_store to set the maximum number of reports that you want to store. Enter a value in upload_cycle to set how many minutes you want to pass between each report generation. packaging: max_reports_to_store: 30 max_size_MB: 100 upload: upload_cycle: 360 Important The costmanagement-metrics-operator creates one report every 360 minutes by default. The default value of 30 reports and 360 minutes gives you 7.5 days of reports. After the maximum number of reports generate, any subsequent reports replace the oldest report in storage. To avoid losing reports, download them from your PVC. Set upload_toggle to false : upload: upload_cycle: 360 upload_toggle: false Set source to empty braces: source: {} Set authentication to empty braces: authentication: {} Click Create . Verification steps Select the CostManagementMetricsConfig that you created. Click YAML view . Verify that a report was created by viewing the data in packaging : packaging: last_successful_packaging_time: `current date and time` max_reports_to_store: 30 max_size_MB: 100 number_of_reports_stored: 1 packaged_files: - >- /tmp/costmanagement-metrics-operator-reports/upload/YYYYMMDDTHHMMSS-cost-mgmt.tar.gz Note After configuration, costmanagement-metrics-operator generates an initial report. These reports are in packaged_files . 1.9.3. Downloading cost reports If you configured the costmanagement-metrics-operator to run on a restricted network, the reports from the persistent volume claims (PVC) are temporarily stored in a workstation. Copy the reports to an unrestricted network. The default configuration saves one week of reports. To avoid losing metrics data, download the reports locally and upload them to Red Hat Hybrid Cloud Console weekly. You can configure any PVC, but by default, most PVCs are ReadWriteOnce . For ReadWriteOnce PVCs, the volume-shell must be attached to the same node as the operator pod. Prerequisites You have a workstation with unrestricted network access. costmanagement-metrics-operator reports in your PVC. Procedure Create the following pod and set claimName to the PVC with the report data: kind: Pod apiVersion: v1 metadata: name: volume-shell namespace: costmanagement-metrics-operator spec: volumes: - name: costmanagement-metrics-operator-reports persistentVolumeClaim: claimName: costmanagement-metrics-operator-data containers: - name: volume-shell image: busybox command: ['sleep', '3600'] volumeMounts: - name: costmanagement-metrics-operator-reports mountPath: /tmp/costmanagement-metrics-operator-reports Run rsync to copy all of the files from the PVC to a local folder: USD oc rsync volume-shell:/tmp/costmanagement-metrics-operator-reports/upload local/path/to/save/folder Confirm that the files were copied. Run the following command to connect to the pod and delete the contents of the upload folder: USD oc rsh volume-shell USD rm /tmp/costmanagement-metrics-operator-reports/upload/* (Optional) Run the following command to delete the pod that you used to connect to the PVC: USD oc delete -f volume-shell.yaml Viewing your PVC usage In the OpenShift tab in Red Hat Hybrid Cloud Console , your PVCs with the highest usage automatically populate under Persistent Volume Claims . To view all PVCs, click more at the end of the section. You can filter your PVC data by the following fields: * Persistent volume claim * Cluster * StorageClass Additional resources For more information about PVCs, see Understanding persistent storage . 1.9.4. Uploading cost reports to console.redhat.com You must manually upload locally stored cost reports from a restricted network to Red Hat Hybrid Cloud Console . Note The default configuration saves one week of reports. Download the reports locally and upload them to Red Hat Hybrid Cloud Console weekly to avoid losing metrics data. Prerequisites You have costmanagement-metrics-operator reports downloaded locally. You created an integration on Red Hat Hybrid Cloud Console . For more information, see Manually creating an Openshift Container Platform integration . You are a Red Hat account user with Organization Administrator entitlements. You have a workstation with unrestricted network access. Procedure To upload your reports to Red Hat Hybrid Cloud Console , make the following edit: Set USERNAME and PASSWORD to your Red Hat Hybrid Cloud Console login credentials and set FILE_NAME to the report that you want to upload: USD curl -vvvv -F "file=@FILE_NAME.tar.gz;type=application/vnd.redhat.hccm.tar+tgz" https://cloud.redhat.com/api/ingress/v1/upload -u USERNAME:PASS Verification steps From cost management , click OpenShift . On the OpenShift details page, confirm that you have OpenShift usage data for your cluster.

Commands:
describe packagemanifests costmanagement-metrics-operator -n openshift-marketplace
echo -n "<red_hat_service_account_client_id>" | base64
echo -n "<red_hat_service_account_client_secret>" | base64
kind: Secret apiVersion: v1 metadata: name: service-account-auth-secret namespace: costmanagement-metrics-operator data: client_id: <base64_encoded_red_hat_service_account_client_id> client_secret: <base64_encoded_red_hat_service_account_client_secret>
apply -f example.yaml
kind: CostManagementMetricsConfig apiVersion: costmanagement-metrics-cfg.openshift.io/v1beta1 metadata: name: costmanagementmetricscfg-sample-v1beta1 namespace: costmanagement-metrics-operator spec: authentication: type: service-account secret_name: service-account-auth-secret packaging: max_reports_to_store: 30 max_size_MB: 100 prometheus_config: collect_previous_data: true context_timeout: 120 disable_metrics_collection_cost_management: false disable_metrics_collection_resource_optimization: false source: check_cycle: 1440 create_source: false name: '' upload: upload_cycle: 360 upload_toggle: true
kind: CostManagementMetricsConfig apiVersion: costmanagement-metrics-cfg.openshift.io/v1beta1 metadata: name: costmanagementmetricscfg-sample-v1beta1 namespace: costmanagement-metrics-operator spec: authentication: type: service-account secret_name: service-account-auth-secret packaging: max_reports_to_store: 30 max_size_MB: 100 prometheus_config: collect_previous_data: true context_timeout: 120 disable_metrics_collection_cost_management: false disable_metrics_collection_resource_optimization: false source: check_cycle: 1440 create_source: true name: 'cluster2' upload: upload_cycle: 360 upload_toggle: true
create_source: false name: ''
create_source: true name: my-openshift-cost-source
prometheus: last_query_start_time: '2021-01-25T20:59:06Z' last_query_success_time: '2021-01-25T20:59:06Z' prometheus_configured: true prometheus_connected: true service_address: 'https://thanos-querier.openshift-monitoring.svc:9091' skip_tls_verification: false
upload: ingress_path: /api/ingress/v1/upload last_successful_upload_time: '2021-01-25T20:59:35Z' last_upload_status: 202 Accepted last_upload_time: '2021-01-25T20:59:35Z' upload: true upload_cycle: 360 upload_wait: 28 validate_cert: true
service-account-auth-secret
client_id
red_hat_service_account_client_id
client_secret
red_hat_service_account_client_secret
authentication: type: token
authentication: secret_name: service-account-auth-secret #Change this line to match your secret name. type: service-account
kind: Subscription metadata: spec: config: resources: <<<<< limits: cpu: 500m memory: 500Mi requests: cpu: 200m memory: 100Mi
packaging: max_reports_to_store: 30 max_size_MB: 100
upload: upload_cycle: 360
upload: upload_cycle: 360 upload_toggle: false
source: {}
authentication: {}
packaging: last_successful_packaging_time: `current date and time` max_reports_to_store: 30 max_size_MB: 100 number_of_reports_stored: 1 packaged_files: - >- /tmp/costmanagement-metrics-operator-reports/upload/YYYYMMDDTHHMMSS-cost-mgmt.tar.gz
kind: Pod apiVersion: v1 metadata: name: volume-shell namespace: costmanagement-metrics-operator spec: volumes: - name: costmanagement-metrics-operator-reports persistentVolumeClaim: claimName: costmanagement-metrics-operator-data containers: - name: volume-shell image: busybox command: ['sleep', '3600'] volumeMounts: - name: costmanagement-metrics-operator-reports mountPath: /tmp/costmanagement-metrics-operator-reports
oc rsync volume-shell:/tmp/costmanagement-metrics-operator-reports/upload local/path/to/save/folder
oc rsh volume-shell rm /tmp/costmanagement-metrics-operator-reports/upload/*
oc delete -f volume-shell.yaml
curl -vvvv -F "file=@FILE_NAME.tar.gz;type=application/vnd.redhat.hccm.tar+tgz" https://cloud.redhat.com/api/ingress/v1/upload -u USERNAME:PASS