$ oc project openshift-infra
As an OpenShift Container Platform administrator, you can view a cluster’s metrics from all containers and components in one user interface. These metrics are also used by horizontal pod autoscalers in order to determine when and how to scale.
This topic describes using Hawkular Metrics as a metrics engine which stores the data persistently in a Cassandra database. When this is configured, CPU, memory and network-based metrics are viewable from the OpenShift Container Platform web console and are available for use by horizontal pod autoscalers.
Heapster retrieves a list of all nodes from the master server, then contacts
each node individually through the
/stats endpoint. From there, Heapster
scrapes the metrics for CPU, memory and network usage, then exports them into Hawkular
Browsing individual pods in the web console displays separate sparkline charts for memory and CPU. The time range displayed is selectable, and these charts automatically update every 30 seconds. If there are multiple containers on the pod, then you can select a specific container to display its metrics.
If resource limits are defined for your
project, then you can also see a donut chart for each pod. The donut chart
displays usage against the resource limit. For example:
145 Available of 200
MiB, with the donut chart showing
55 MiB Used.
The components for cluster metrics must be deployed to the openshift-infra project. This allows horizontal pod autoscalers to discover the Heapster service and use it to retrieve metrics that can be used for autoscaling.
All of the following commands in this topic must be executed under the openshift-infra project. To switch to the openshift-infra project:
$ oc project openshift-infra
To enable cluster metrics, you must next configure the following:
You must configure service accounts for:
The Metrics Deployer will be discussed in a later step, but you must first set up a service account for it:
Grant view permissions to the Hawkular Metrics service:
$ oc adm policy add-role-to-user view system:serviceaccount:openshift-infra:hawkular -n openshift-infra
Create a metrics-deployer service account:
$ oc create -f - <<API apiVersion: v1 kind: ServiceAccount metadata: name: metrics-deployer secrets: - name: metrics-deployer API
Before it can deploy components, the metrics-deployer service account must
also be granted the
edit permission for the openshift-infra project:
$ oadm policy add-role-to-user \ edit system:serviceaccount:openshift-infra:metrics-deployer
The Heapster component requires access to the master server to list all
available nodes and access the
/stats endpoint for each node. Before it can do
this, the Heapster service account requires the
$ oadm policy add-cluster-role-to-user \ cluster-reader system:serviceaccount:openshift-infra:heapster
The Heapster service account is created automatically during the Deploying the Metrics Components step.
Running OpenShift Container Platform cluster metrics with persistent storage means that your metrics will be stored to a persistent volume and be able to survive a pod being restarted or recreated. This is ideal if you require your metrics data to be guarded from data loss. For production environments it is highly recommended to configure persistent storage for your metrics pods.
The size of the persisted volume can be specified with the
parameter. By default it is set to 10 GB, which may or may not be sufficient
for the size of the cluster you are using. If you require more space, for
instance 100 GB, you could specify it with something like this:
$ oc process -f metrics-deployer.yaml \ -v HAWKULAR_METRICS_HOSTNAME=hawkular-metrics.example.com \ -v CASSANDRA_PV_SIZE=100Gi \ | oc create -f -
The size requirement of the Cassandra storage is dependent on the number of pods. It is the administrator’s responsibility to ensure that the size requirements are sufficient for their setup and to monitor usage to ensure that the disk does not become full.
After the metrics deployer runs, the output of
oc get pods should resemble the following:
# oc get pods -n openshift-infra NAME READY STATUS RESTARTS AGE hawkular-cassandra-1-l5y4g 1/1 Running 0 17h hawkular-metrics-1t9so 1/1 Running 0 17h heapster-febru 1/1 Running 0 17h
OpenShift Container Platform metrics are stored using the Cassandra database, which is
deployed with settings of
These values should cover most OpenShift Container Platform metrics installations, but you
can modify them in the
prior to deploying cluster metrics.
By default, metrics data is stored for 7 days. You can configure this with the
METRIC_DURATION parameter in the
metrics.yaml configuration file.
After seven days, Cassandra begins to purge the oldest metrics data.
Metrics data for deleted pods and projects is not automatically
purged; it is only removed once the data is over seven days old.
If the Cassandra persisted volume runs out of sufficient space, then data loss will occur.
For cluster metrics to work with persistent storage, ensure that the persistent volume has the ReadWriteOnce access mode. If this mode is not active, then the persistent volume claim cannot locate the persistent volume, and Cassandra fails to start.
OpenShift Container Platform metrics also supports
dynamically-provisioned persistent volumes.
To use this feature with OpenShift Container Platform metrics, it is necessary to add an
additional flag to the metrics-deployer:
You can use EBS, GCE, and Cinder storage back-ends to
dynamically provision persistent volumes.
In tests performed with with 210 and 990 OpenShift Container Platform nodes, where 10500 pods and 11000 pods were monitored respectively, the Cassandra database grew at the speed shown in the table below:
|Number of Nodes||Number of Pods||Cassandra Storage growth speed||Cassandra storage growth per day||Cassandra storage growth per week|
500 MB per hour
1 GB per hour
In the above calculation, approximately 20% of the expected size was added as overhead to ensure that the storage requirements do not exceed calculated value.
METRICS_RESOLUTION values are kept at the
7 days and
15 seconds respectively), it is safe to plan Cassandra
storage size requrements for week, as in the values above.
Because OpenShift Container Platform metrics uses the Cassandra database as a datastore for
metrics data, if
Known Issues and Limitations
Testing found that the
heapster metrics component is capable of handling up to
12000 pods. If the amount of pods exceed that number, Heapster begins to fall
behind in metrics processing, resulting in the possibility of metrics graphs no
longer appearing. Work is ongoing to increase the number of pods that Heapster
can gather metrics on, as well as upstream development of alternate
Running OpenShift Container Platform cluster metrics with non-persistent storage means that any stored metrics will be deleted when the pod is deleted. While it is much easier to run cluster metrics with non-persistent data, running with non-persistent data does come with the risk of permanent data loss. However, metrics can still survive a container being restarted.
In order to use non-persistent storage, you must set the
false for the Metrics Deployer.
When using non-persistent storage, metrics data will be written to /var/lib/origin/openshift.local.volumes/pods on the node where the Cassandra pod is running. Ensure /var has enough free space to accommodate metrics storage.
The Metrics Deployer will auto-generate self-signed certificates for use between its components and will generate a re-encrypting route to expose the Hawkular Metrics service. This route is what allows the web console to access the Hawkular Metrics service.
In order for the browser running the web console to trust the connection through this route, it must trust the route’s certificate. This can be accomplished by providing your own certificates signed by a trusted Certificate Authority. The Metric Deployer’s secret allows you to pass your own certificates which it will then use when creating the route.
If you do not wish to provide your own certificates, the router’s default certificate will be used instead.
hawkular-metrics.pem value needs to contain the certificate in its .pem
format. You may also need to provide the certificate for the Certificate Authority
which signed this pem file via the
$ oc secrets new metrics-deployer \ hawkular-metrics.pem=/home/openshift/metrics/hm.pem \ hawkular-metrics-ca.cert=/home/openshift/metrics/hm-ca.cert
When these secrets are provided, the deployer uses these values to specify the
caCertificate values for the re-encrypting route it generated.
For more information, please see the re-encryption route documentation.
hawkular-metrics.pem value is not specified, the re-encrypting route will
use the router’s default certificate, which may not be trusted by browsers.
A secret named metrics-deployer will still be required in this situation. This can be considered a "dummy" secret since the secret it specifies is not actually used by the component.
To create a "dummy" secret that does not specify a certificate value:
$ oc secrets new metrics-deployer nothing=/dev/null
The following table contains more advanced configuration options, detailing all the secrets which can be used by the deployer:
The pem file to use for the Hawkular Metrics certificate used for the
re-encrypting route. This certificate must contain the host name used by the
The certificate for the CA used to sign the hawkular-metrics.pem. This is optional if the hawkular-metrics.pem does not contain the CA certificate directly.
The certificate for Heapster to use. This is auto-generated if unspecified.
The key to use with the Heapster certificate. This is ignored if heapster.cert is not specified
The certificate that generates heapster.cert. This is required if heapster.cert is specified. Otherwise, the main CA for the OpenShift Container Platform installation is used. In order for horizontal pod autoscaling to function properly, this should not be overridden.
A file containing a comma-separated list of CN to accept from certificates
signed with the specified CA. By default, this is set to allow the
OpenShift Container Platform service proxy to connect. If you override this, make sure to
The OpenShift Container Platform installer uses a template to deploy the metrics components. The default template can be found at the following path:
In case you need to make any changes to this file, copy it to another directory with the file name metrics-deployer.yaml and refer to the new location when using it in the following sections.
The deployer template parameter options and their defaults are listed in the default metrics-deployer.yaml file. If required, you can override these values when creating the Metrics Deployer.
The number of days metrics should be stored.
The persistent volume size for each of the Cassandra nodes.
The number of initial Cassandra nodes to deploy.
Set to true for persistent storage; set to false to use non-persistent storage.
Set to true to allow for dynamically provisioned storage.
If set to true, the deployer will try to delete all the existing components before trying to redeploy.
External host name where clients can reach Hawkular Metrics. This is the FQDN of the machine running the router pod.
Internal URL for the master, for authentication retrieval.
Specify version for metrics components. For example, for openshift/origin-metrics-deployer:latest, set version to latest.
Specify prefix for metrics components. For example, for openshift/origin-metrics-deployer:latest, set prefix to openshift/origin-.
Can be set to:
Can be set to true to disable the preflight checks. This allows the deployer to continue even if the preflight check has failed.
Sets whether user accounts should be able to write metrics. Defaults to
The only required parameter is
HAWKULAR_METRICS_HOSTNAME. This value is
required when creating the deployer, because it specifies the host name for the
Hawkular Metrics route. This
value should correspond to a fully qualified domain name. You must know
the value of
configuring the console for metrics access.
If you are using
storage with Cassandra, it is the administrator’s responsibility to set a
sufficient disk size for the cluster using the
It is also the administrator’s responsibility to monitor disk usage to make sure
that it does not become full.
Data loss will result if the Cassandra persisted volume runs out of sufficient space.
All of the other parameters are optional and allow for greater customization.
For instance, if you have a custom install in which the Kubernetes master is not
available under https://kubernetes.default.svc:443 you can specify the value
to use instead with the
MASTER_URL parameter. To deploy a specific version
of the metrics components, use the
It is highly recommended to not use latest for the IMAGE_VERSION. The latest version corresponds to the very latest version available and can cause issues if it brings in a newer version not meant to function on the version of OpenShift Container Platform you are currently running.
Because deploying and configuring all the metric components is handled by the Metrics Deployer, you can simply deploy everything in one step.
The following examples show you how to deploy metrics with and without persistent storage using the default template parameters. Optionally, you can specify any of the template parameters when calling these commands.
The following command sets the Hawkular Metrics route to use hawkular-metrics.example.com and is deployed using persistent storage.
You must have a persistent volume of sufficient size available.
$ oc new-app --as=system:serviceaccount:openshift-infra:metrics-deployer \ -f metrics-deployer.yaml \ -p HAWKULAR_METRICS_HOSTNAME=hawkular-metrics.example.com
The following command sets the Hawkular Metrics route to use hawkular-metrics.example.com and deploy without persistent storage.
$ oc new-app --as=system:serviceaccount:openshift-infra:metrics-deployer \ -f metrics-deployer.yaml \ -p HAWKULAR_METRICS_HOSTNAME=hawkular-metrics.example.com \ -p USE_PERSISTENT_STORAGE=false
Because this is being deployed without persistent storage, metric data loss can occur.
The metrics deployer does some validation both before and after deployment. If
the pre-flight validation fails, the environment for deployment is considered
unsuitable and the deployment is aborted. However, you can add
IGNORE_PREFLIGHT=true to the deployer parameters if you believe the
validation has erred.
If post-deployment validation fails, the deployer finishes in an Error state, which indicates that you should check the deployer logs for issues that may require addressing. For example, the validation may detect that the external hawkular-metrics route is not actually in use, because the route was already created somewhere else. The validation output at the end of a deployment should explain as clearly as possible any issues it finds and what you can do to address them.
Once you have addressed deployment validation issues, you can re-run just the
validation by running the deployer again with the
added, for example:
$ oc new-app --as=system:serviceaccount:openshift-infra:metrics-deployer \ -f metrics-deployer.yaml \ -p HAWKULAR_METRICS_HOSTNAME=hawkular-metrics.example.com \ -p MODE=validate
There is also a diagnostic for metrics:
$ oadm diagnostics MetricsApiProxy
The OpenShift Container Platform web console uses the data coming from the Hawkular Metrics
service to display its graphs. The URL for accessing the Hawkular Metrics
service must be configured via the
metricsPublicURL option in the
configuration file (/etc/origin/master/master-config.yaml). This URL
corresponds to the route created with the
parameter during the
of the metrics components.
You must be able to resolve the
For example, if your
HAWKULAR_METRICS_HOSTNAME corresponds to
hawkular-metrics.example.com, then you must make the following change in the
assetConfig: ... metricsPublicURL: "https://hawkular-metrics.example.com/hawkular/metrics"
Once you have updated and saved the master-config.yaml file, you must restart your OpenShift Container Platform instance.
When your OpenShift Container Platform server is back up and running, metrics will be displayed on the pod overview pages.
If you are using self-signed certificates, remember that the Hawkular Metrics
service is hosted under a different host name and uses different certificates
than the console. You may need to explicitly open a browser tab to the value
To avoid this issue, use certificates which are configured to be acceptable by your browser.
To access and manage metrics more directly, use the Hawkular Metrics API.
When accessing Hawkular Metrics via the API, you will only be able to perform
reads. Writing metrics has been disabled by default. If you want for individual
users to also be able to write metrics, you must set the
However, it is recommended to use the default configuration and only have metrics enter the system via Heapster. If write access is enabled, any user will be able to write metrics to the system, which can affect performance and cause Cassandra disk usage to unpredictably increase.
The Hawkular Metrics documentation covers how to use the API, but there are a few differences when dealing with the version of Hawkular Metrics configured for use on OpenShift Container Platform:
Hawkular Metrics is a multi-tenanted application. It is configured so that a project in OpenShift Container Platform corresponds to a tenant in Hawkular Metrics.
As such, when accessing metrics for a project named MyProject you must set the Hawkular-Tenant header to MyProject.
There is also a special tenant named _system which contains system level metrics. This requires either a cluster-reader or cluster-admin level privileges to access.
The Hawkular Metrics service will authenticate the user against OpenShift Container Platform to determine if the user has access to the project it is trying to access.
Hawkular Metrics accepts a bearer token from the client and verifies that token with the OpenShift Container Platform server using a SubjectAccessReview. If the user has proper read privileges for the project, they are allowed to read the metrics for that project. For the _system tenant, the user requesting to read from this tenant must have cluster-reader permission.
When accessing the Hawkular Metrics API, you must pass a bearer token in the Authorization header.
One set of metrics pods (Cassandra/Hawkular/Heapster) is able to monitor at least 10,000 pods.
Autoscaling the metrics components, such as Hawkular and Heapster, is not supported by OpenShift Container Platform.
Pay attention to system load on nodes where OpenShift Container Platform metrics pods run. Use that information to determine if it is necessary to scale out a number of OpenShift Container Platform metrics pods and spread the load across multiple OpenShift Container Platform nodes. Scaling OpenShift Container Platform metrics heapster pods is not recommended.
If persistent storage was used to deploy OpenShift Container Platform metrics, then you must create a persistent volume (PV) for the new Cassandra pod to use before you can scale out the number of OpenShift Container Platform metrics Cassandra pods. However, if Cassandra was deployed with dynamically provisioned PVs, then this step is not necessary.
The Cassandra nodes use persistent storage, therefore scaling up or down is not possible with replication controllers.
Scaling a Cassandra cluster requires you to use the
hawkular-cassandra-node template. By default, the Cassandra cluster is a single-node cluster.
To scale up the number of OpenShift Container Platform metrics hawkular pods to two replicas, run:
# oc scale -n openshift-infra --replicas=2 rc hawkular-metrics
Alternatively, update your inventory file and re-run the deployment.
If you add a new node to or remove an existing node from a Cassandra cluster, the data stored in the cluster rebalances across the cluster.
To scale down:
If remotely accessing the container, run the following for the Cassandra node you want to remove:
$ oc exec -it <hawkular-cassandra-pod> nodetool decommission
If locally accessing the container, run the following instead:
$ oc rsh <hawkular-cassandra-pod> nodetool decommission
This command can take a while to run since it copies data across the cluster.
You can monitor the decommission progress with
nodetool netstats -H.
Once the previous command succeeds, scale down the
rc for the Cassandra instance to
# oc scale -n openshift-infra --replicas=0 rc <hawkular-cassandra-rc>
This will remove the Cassandra pod.
If the scale down process completed and the existing Cassandra nodes are
functioning as expected, you can also delete the