Observability plug-in CLI

Refer to these commands to create and manage logging and monitoring configurations for your IBM Cloud Kubernetes Service cluster.

Looking for ibmcloud ks commands? See the IBM Cloud Kubernetes Service CLI reference.

Logging commands

`ibmcloud ob logging agent discover`

Virtual Private Cloud Classic infrastructure

Discover Log Analysis agents that you manually installed in your cluster without using the IBM Cloud Kubernetes Service observability plug-in, and make this logging configuration visible to the plug-in so that you can use the observability plug-in commands and functions in the IBM Cloud console to manage this configuration.

ibmcloud ob logging agent discover --cluster CLUSTER [--instance LOGGING_INSTANCE]

Minimum required permissions:

Administrator platform access role and Manager service access role for all Kubernetes namespaces in IBM Cloud Kubernetes Service
Viewer platform access role for IBM Log Analysis

Command options: --cluster CLUSTER : The name or ID of the cluster where you manually created a Log Analysis configuration without using the IBM Cloud Kubernetes Service observability plug-in. To retrieve your cluster name or ID, run ibmcloud ks clusters. This value is required.

--instance LOGGING_INSTANCE: The ID or name of the IBM Log Analysis service instance that you use in your logging configuration. This value is optional. If you don't provide this value, the IBM Log Analysis service instance is automatically retrieved.

`ibmcloud ob logging config create`

Virtual Private Cloud Classic infrastructure

Create a logging configuration for your cluster to automatically collect pod logs and send them to IBM Log Analysis.

This command deploys a Log Analysis agent as a Kubernetes daemon set in your cluster. The agent collects logs with the extension *.log and extensionless files that are stored in the /var/log directory of your pod from all namespaces, including kube-system. For more information, see Forwarding cluster and app logs to IBM Log Analysis. For more information about IBM Log Analysis, see Securing your data.

ibmcloud ob logging config create --cluster CLUSTER --instance LOGGING_INSTANCE [--logdna-ingestion-key INGESTION_KEY] [--private-endpoint]

Minimum required permissions:

Administrator platform access role and Manager service access role for all Kubernetes namespaces in IBM Cloud Kubernetes Service
Editor platform access role and Manager server access role for IBM Log Analysis

Command options:

--cluster CLUSTER: The name or ID of the cluster for which you want to create a logging configuration for IBM Log Analysis. To retrieve your cluster name or ID, run ibmcloud ks clusters. This value is required.
--instance LOGGING_INSTANCE: The ID or name of the IBM Log Analysis service instance that you want to use to create the logging configuration. The service instance must be in the same IBM Cloud account as your cluster, but can be in a different resource group or region than your cluster. To create a service instance, follow the steps in Provision an instance. This value is required.
--logdna-ingestion-key INGESTION_KEY: The Log Analysis ingestion key that you want to use for your configuration. This value is optional. If you don't specify this option, the latest ingestion key is automatically retrieved.
--private-endpoint: When you add this option to your command, the private cloud service endpoint is used to connect to IBM Log Analysis. To use the private cloud service endpoint, your cluster must be enabled for using private cloud service endpoints. 1.30 and later: If your cluster has outbound traffic protection enabled, you must specify the private endpoint option to use logging.

Example command

ibmcloud ob logging config create --cluster mycluster --instance mylogna

`ibmcloud ob logging config delete`

Virtual Private Cloud Classic infrastructure

Delete a Log Analysis configuration from your cluster.

To remove logging configurations that you manually set up without using the IBM Cloud Kubernetes Service observability plug-in, you must first make this configuration available to the plug-in by using the ibmcloud ob logging agent discover command.

When you delete the logging configuration, the components that are deleted depend on how you created the logging configuration. For logging configurations that were created with the ibmcloud ob logging config create command, the daemon set for the Log Analysis agent, the ConfigMap, and secret are removed from your cluster, and pod logs are no longer sent to your IBM Log Analysis service instance. Logging configurations that you manually created and made visible to the plug-in by using the ibmcloud ob logging agent discover command, only the ConfigMap is removed. Your daemon set, secret, and the Log Analysis agent are still deployed to your cluster and you must manually remove them. Because the ConfigMap is removed, pod logs are no longer sent to your IBM Log Analysis service instance. Independent of how you created the configuration, existing log data is still available in IBM Log Analysis until your selected retention period ends.

ibmcloud ob logging config delete --cluster CLUSTER --instance LOGGING_INSTANCE

Minimum required permissions:

Administrator platform access role and Manager service access role for the ibm-observe Kubernetes namespaces in IBM Cloud Kubernetes Service.
Viewer platform access role for IBM Log Analysis

Command options:

--cluster CLUSTER: The name or ID of the cluster for which you want to delete an existing Log Analysis configurations. To retrieve the cluster name or ID, run ibmcloud ks clusters. This value is required.
--instance LOGGING_INSTANCE: The ID or name of the IBM Log Analysis service instance that you used in your logging configuration. To retrieve the service instance name, run ibmcloud resource service-instances. This value is required.

Example command

ibmcloud ob logging config delete --cluster mycluster --instance mylogginginstance

`ibmcloud ob logging config list`

Virtual Private Cloud Classic infrastructure

List all Log Analysis configurations that were created for your cluster with the IBM Cloud Kubernetes Service observability plug-in.

To list logging configurations that you manually set up without using the IBM Cloud Kubernetes Service observability plug-in, you must first make this configuration available to the plug-in by using the ibmcloud ob logging agent discover command.

ibmcloud ob logging config list --cluster CLUSTER

Minimum required permissions:

Viewer platform access role and Reader service access role for the ibm-observe Kubernetes namespaces in IBM Cloud Kubernetes Service.
Viewer platform access role for IBM Log Analysis

Command options:

--cluster CLUSTER: The name or ID of the cluster for which you want to list existing Log Analysis configurations. This value is required.

`ibmcloud ob logging config enable public-endpoint|private-endpoint`

Virtual Private Cloud Classic infrastructure

Use the public or private cloud service endpoint to send data from your cluster to your Log Analysis service instance.

To use the private cloud service endpoint, your cluster must be enabled for using private cloud service endpoints.

ibmcloud ob logging config enable public-endpoint|private-endpoint --cluster CLUSTER --instance LOGGING_INSTANCE

Minimum required permissions:

Administrator platform access role and Manager service access role for all Kubernetes namespaces in IBM Cloud Kubernetes Service
Editor platform access role and Manager server access role for IBM Log Analysis

Command options:

public-endpoint|private-endpoint: Enter public-endpoint to use the public cloud service endpoint of your IBM Log Analysis service instance, or private-endpoint to use the private cloud service endpoint to send logs from your cluster. This value is required. To use the private cloud service endpoint, your cluster must be enabled for using private cloud service endpoints.
--cluster CLUSTER: The name or ID of the cluster for which you want to enable the private or public cloud service endpoint to connect to your Log Analysis service instance. To retrieve your cluster name or ID, run ibmcloud ks clusters. This value is required.
--instance LOGGING_INSTANCE: The ID or name of the IBM Log Analysis service instance to which you want to connect by using the public or private cloud service endpoint. To retrieve the name, run ibmcloud resource service-instances. This value is required.

`ibmcloud ob logging config replace`

Virtual Private Cloud Classic infrastructure

Replace the IBM Log Analysis service instance or ingestion key that you use in your Log Analysis configuration.

Replace the ingestion key of an existing IBM Log Analysis service instance:

ibmcloud ob logging config replace --cluster CLUSTER --instance LOGGING_INSTANCE --logdna-ingestion-key INGESTION_KEY

Replace the IBM Log Analysis service instance:

ibmcloud ob logging config replace --cluster CLUSTER --instance LOGGING_INSTANCE  --new-instance LOGGING_INSTANCE_NEW [--logdna-ingestion-key INGESTION_KEY]

Minimum required permissions:

Administrator platform access role and Manager service access role for all Kubernetes namespaces in IBM Cloud Kubernetes Service
Editor platform access role and Manager server access role for IBM Log Analysis

Command options:

--cluster CLUSTER: The name or ID of the cluster for which you want to change the IBM Log Analysis ingestion key or service instance that you use in your Log Analysis configuration. This value is required.
--instance LOGGING_INSTANCE: The ID or name of the IBM Log Analysis service instance for which you want to change the ingestion key, or the IBM Log Analysis service instance that you want to replace. To retrieve the name, run ibmcloud ob logging config list --cluster <cluster_name_or_ID>. This value is required.
--new-instance LOGGING_INSTANCE_NEW: If you want to replace the IBM Log Analysis service instance that you use in your Log Analysis configuration, enter the ID or name of the new IBM Log Analysis service instance that you want to use. This value is required if you want to replace the IBM Log Analysis service instance. If you want to replace the ingestion key, don't include this command option.
--logdna-ingestion-key INGESTION_KEY: The Log Analysis ingestion key that you want to use for your configuration. For information about how to retrieve the ingestion key, see Get the ingestion key through the IBM Cloud UI. This value is required if you want to replace the ingestion key, and optional if you want to replace the IBM Log Analysis service instance. If you don't provide the ingestion key when replacing the IBM Log Analysis service instance, the ingestion key that was last added is retrieved automatically.

`ibmcloud ob logging config show`

Virtual Private Cloud Classic infrastructure

Show the details of a Log Analysis configuration.

To show the details of logging configurations that you manually set up without using the IBM Cloud Kubernetes Service observability plug-in, you must first make this configuration available to the plug-in by using the ibmcloud ob logging agent discover command.

ibmcloud ob logging config show --cluster CLUSTER --instance LOGGING_INSTANCE

Minimum required permissions:

Viewer platform access role and Reader service access role for the ibm-observe Kubernetes namespaces in IBM Cloud Kubernetes Service.
Viewer platform access role for IBM Log Analysis

Command options:

--cluster CLUSTER: The name or ID of the cluster for which you want to list existing Log Analysis configurations. To retrieve your cluster name or ID, run ibmcloud ks clusters. This value is required.
--instance LOGGING_INSTANCE: The ID or name of the IBM Log Analysis service instance for which you want to show the logging configuration. To retrieve the name, run ibmcloud resource service-instances. This value is required.

Monitoring commands

`ibmcloud ob monitoring agent discover`

Virtual Private Cloud Classic infrastructure

Discover Monitoring agents that you manually installed in your cluster without using the IBM Cloud Kubernetes Service observability plug-in, and make this monitoring configuration visible to the plug-in so that you can use the observability plug-in commands and functionality in the IBM Cloud console to manage this configuration.

ibmcloud ob monitoring agent discover --cluster CLUSTER [--instance MONITORING_INSTANCE]

Minimum required permissions:

Administrator platform access role and Manager service access role for all Kubernetes namespaces in IBM Cloud Kubernetes Service
Viewer platform access role for IBM Cloud Monitoring

Command options:

--cluster CLUSTER: The name or ID of the cluster where you manually created a Monitoring configuration without using the IBM Cloud Kubernetes Service observability plug-in. To retrieve your cluster name or ID, run ibmcloud ks clusters. This value is required.
--instance MONITORING_INSTANCE: The ID or name of the IBM Cloud Monitoring service instance that you use in your monitoring configuration. This value is optional. If you don't provide this value, the IBM Cloud Monitoring service instance is automatically retrieved

`ibmcloud ob monitoring config create`

Virtual Private Cloud Classic infrastructure

Create a monitoring configuration for your cluster to automatically collect cluster and pod metrics, and send them to IBM Cloud Monitoring.

This command deploys a Monitoring agent as a Kubernetes daemon set in your cluster. The agent collects cluster and pod metrics, such as the worker node CPU and memory usage, and the amount of incoming and outgoing network traffic for your pods. For more information, see Forwarding cluster and app metrics to IBM Cloud Monitoring.

ibmcloud ob monitoring config create --cluster CLUSTER --instance MONITORING_INSTANCE [--sysdig-access-key ACCESS_KEY] [--private-endpoint]

Minimum required permissions:

Administrator platform access role and Manager service access role for all Kubernetes namespaces in IBM Cloud Kubernetes Service
Editor platform access role and Manager server access role for IBM Cloud Monitoring

Command options:

--cluster CLUSTER: The name or ID of the cluster for which you want to create a monitoring configuration for IBM Cloud Monitoring. To retrieve your cluster name or ID, run ibmcloud ks clusters. This value is required.
--instance MONITORING_INSTANCE: The ID or name of the IBM Cloud Monitoring service instance that you want to use to create the monitoring configuration. The service instance must be in the same IBM Cloud account as your cluster, but can be in a different resource group or region than your cluster. To create a service instance, follow the steps in Provision an instance. This value is required.
--sysdig-access-key ACCESS_KEY: The Monitoring access key that you want to use for your configuration. This value is optional. If you don't specify this option, the latest access key is used for your configuration.
--private-endpoint: When you add this option to your command, the private cloud service endpoint is used to connect to IBM Cloud Monitoring. To use the private cloud service endpoint, your cluster must be enabled for using private cloud service endpoints. 1.30 and later: If your cluster has outbound traffic protection enabled, you must specify the private endpoint option to use monitoring.

Example command

ibmcloud ob monitoring config create --cluster mycluster --instance mymonitoringinstance

`ibmcloud ob monitoring config delete`

Virtual Private Cloud Classic infrastructure

Delete a Monitoring configuration from your cluster.

To remove monitoring configurations that you manually set up without using the IBM Cloud Kubernetes Service observability plug-in, you must first make this configuration available to the plug-in by using the ibmcloud ob monitoring agent discover command.

When you delete the monitoring configuration, the components that are deleted depend on how you created the monitoring configuration. For monitoring configurations that were created with the ibmcloud ob monitoring config create command, the daemon set for the Monitoring agent, the ConfigMap, and secret are removed from your cluster, and metrics are no longer sent to your IBM Cloud Monitoring service instance. Monitoring configurations that you manually created and made visible to the plug-in by using the ibmcloud ob monitoring agent discover command, only the ConfigMap is removed. Your daemon set, secret, and the Monitoring agent are still deployed to your cluster and you must manually remove them. Because the ConfigMap is removed, metrics are no longer sent to your IBM Cloud Monitoring service instance. Independent of how you created the configuration, existing metrics are still available in IBM Cloud Monitoring until your selected retention period ends.

ibmcloud ob monitoring config delete --cluster CLUSTER --instance MONITORING_INSTANCE

Minimum required permissions:

Administrator platform access role and Manager service access role for the ibm-observe Kubernetes namespaces in IBM Cloud Kubernetes Service.
Viewer platform access role for IBM Cloud Monitoring

Command options:

--cluster CLUSTER: The name or ID of the cluster for which you want to delete an existing Monitoring configuration. To retrieve the cluster name or ID, run ibmcloud ks cluster ls. This value is required.
--instance MONITORING_INSTANCE: The ID or name of the IBM Cloud Monitoring service instance that you used in your monitoring configuration. To retrieve the service instance name, run ibmcloud resource service-instances. This value is required.

Example command

ibmcloud ob monitoring config delete --cluster mycluster --instance mymonitoringinstance

`ibmcloud ob monitoring config list`

Virtual Private Cloud Classic infrastructure

List all Monitoring configurations that were created for your cluster with the IBM Cloud Kubernetes Service observability plug-in.

To list monitoring configurations that you manually set up without using the IBM Cloud Kubernetes Service observability plug-in, you must first make this configuration available to the plug-in by using the ibmcloud ob monitoring agent discover command.

ibmcloud ob monitoring config list --cluster CLUSTER

Minimum required permissions:

Viewer platform access role and Reader service access role for the ibm-observe Kubernetes namespaces in IBM Cloud Kubernetes Service.
Viewer platform access role for IBM Cloud Monitoring

Command options:

--cluster CLUSTER: The name or ID of the cluster for which you want to list existing Monitoring configurations. This value is required.

`ibmcloud ob monitoring config enable public-endpoint|private-endpoint`

Virtual Private Cloud Classic infrastructure

Use the public or private cloud service endpoint to send metrics from your cluster to your Monitoring service instance.

ibmcloud ob monitoring config enable public-endpoint|private-endpoint --cluster CLUSTER --instance MONITORING_INSTANCE

Minimum required permissions:

Administrator platform access role and Manager service access role for all Kubernetes namespaces in IBM Cloud Kubernetes Service
Editor platform access role and Manager server access role for IBM Cloud Monitoring

Command options:

public-endpoint|private-endpoint: Enter public-endpoint to use the public cloud service endpoint of your IBM Cloud Monitoring service instance, or private-endpoint to use the private cloud service endpoint to send metrics from your cluster. This value is required. To use the private cloud service endpoint, your cluster must be enabled for using private cloud service endpoints.
--cluster CLUSTER: The name or ID of the cluster for which you want to enable the private or public cloud service endpoint to connect to your Monitoring service instance. To retrieve your cluster name or ID, run ibmcloud ks clusters. This value is required.
--instance MONITORING_INSTANCE: The ID or name of the IBM Cloud Monitoring service instance to which you want to connect by using the public or private cloud service endpoint. To retrieve the name, run ibmcloud resource service-instances. This value is required.

`ibmcloud ob monitoring config replace`

Virtual Private Cloud Classic infrastructure

Replace the IBM Cloud Monitoring service instance or service access key that you use in your Monitoring configuration.

Replace the service access key of an existing IBM Cloud Monitoring service instance:

ibmcloud ob logging config replace --cluster CLUSTER --instance MONITORING_INSTANCE --sysdig-access-key ACCESS_KEY

Replace the IBM Cloud Monitoring service instance:

ibmcloud ob logging config replace --cluster CLUSTER --instance MONITORING_INSTANCE  --new-instance MONITORING_INSTANCE_NEW [--sysdig-access-key ACCESS_KEY]

Minimum required permissions:

Administrator platform access role and Manager service access role for all Kubernetes namespaces in IBM Cloud Kubernetes Service
Editor platform access role and Manager server access role for IBM Cloud Monitoring

Command options:

--cluster CLUSTER: The name or ID of the cluster for which you want to change the IBM Cloud Monitoring service access key or service instance that you use in your Monitoring configuration. This value is required.
--instance MONITORING_INSTANCE: The ID or name of the IBM Cloud Monitoring service instance for which you want to change the service access key, or the IBM Cloud Monitoring service instance that you want to replace. To retrieve the name, run ibmcloud ob monitoring config list --cluster <cluster_name_or_ID>. This value is required.
--new-instance MONITORING_INSTANCE_NEW: If you want to replace the IBM Cloud Monitoring service instance that you use in your Monitoring configuration, enter the ID or name of the new IBM Cloud Monitoring service instance that you want to use. This value is required if you want to replace the IBM Cloud Monitoring service instance. If you want to replace the service access key, don't include this command option.
--sysdig-access-key ACCESS_KEY: The Monitoring service access key that you want to use for your configuration. For information about how to retrieve the service access key, see Getting the access key through the IBM Cloud UI. This value is required if you want to replace the service access key, and optional if you want to replace the IBM Cloud Monitoring service instance. If you don't provide the service access key when replacing the IBM Cloud Monitoring service instance, the service access key that was last added is retrieved automatically.

`ibmcloud ob monitoring config show`

Virtual Private Cloud Classic infrastructure

Show the details of a Monitoring configuration.

To show the details of monitoring configurations that you manually set up without using the IBM Cloud Kubernetes Service observability plug-in, you must first make this configuration available to the plug-in by using the ibmcloud ob monitoring agent discover command.

ibmcloud ob monitoring config show --cluster CLUSTER --instance MONITORING_INSTANCE

Minimum required permissions:

Viewer platform access role and Reader service access role for the ibm-observe Kubernetes namespaces in IBM Cloud Kubernetes Service.
Viewer platform access role for IBM Log Analysis

Command options:

--cluster CLUSTER: The name or ID of the cluster for which you want to list existing Monitoring configurations. To retrieve your cluster name or ID, run ibmcloud ks clusters. This value is required.
--instance LOGGING_INSTANCE: The ID or name of the IBM Cloud Monitoring service instance for which you want to show the monitoring configuration. To retrieve the name, run ibmcloud resource service-instances. This value is required.