--- name: cloud-logs-agent-helm-os-deploy title: Deploying the Logging agent v1.6.x for OpenShift clusters description: You can use a Helm chart to deploy the Logging agent v1.6.x to collect and route infrastructure and application logs from an OpenShift cluster to an IBM Cloud Logs instance. last-updated: 2026-06-04 --- > ## Documentation Index > The table of contents for this documentation set is at https://cloud.ibm.com/docs/cloud-logs?format=markdown > The index for all IBM Cloud docs is at: https://cloud.ibm.com/docs/llms.txt > Use these files to discover more information as needed. # Deploying the Logging agent v1.6.x for OpenShift clusters {: #agent-helm-os-deploy} You can use a Helm chart to deploy the Logging agent v1.6.x to collect and route infrastructure and application logs from an OpenShift cluster to an IBM Cloud Logs instance. {: shortdesc} You can also use Terraform IBM Modules (TIM) for [Logging agent](https://registry.terraform.io/modules/terraform-ibm-modules/logs-agent/ibm/latest){: external} to deploy and configure the logs agent on supported OpenShift clusters. This module automates the Helm-based deployment and key configuration settings by using Infrastructure as Code (IaC) automation. {: tip} Complete the following steps to deploy an agent on an OpenShift cluster: ## Before you begin {: #agent-helm-os-deploy-prereqs} - Make sure you have access to an Red Hat OpenShift on IBM Cloud (`OpenShift`) cluster with permissions to create namespaces and deploy the agent. - Install the following CLIs: - The IBM Cloud CLI to log in to the IBM Cloud and manage IBM Cloud services such as creating an API key. - The Openshift CLI to manage the cluster from the command line. [Learn more](https://cloud.ibm.com/docs/openshift?topic=openshift-cli-install&format=markdown). - The latest release of the version 3 [Helm CLI](https://github.com/helm/helm/releases) - Read about [the Logging agent](https://cloud.ibm.com/docs/cloud-logs?topic=cloud-logs-agent-about&format=markdown). - Check the agent versions that are available. For more information, see [Checking the available agent versions](https://cloud.ibm.com/docs/cloud-logs?topic=cloud-logs-check-agent-versions&format=markdown). Note that the version of the Helm chart will match the version of the agent - for example, if you are using version 1.3.0 of the agent there's a Helm chart with version 1.3.0 that accompanies that version. ## Step 1. Define the authentication method for the agent {: #agent-helm-os-deploy-step1} Choose the type of identity and the authentication method for the agent. Then, create a trusted profile or an API key. The role that is required for sending logs to IBM Cloud Logs is `Sender`. You can use a service ID or a trusted profile as the identity that is used by the agent to authenticate with the IBM® Cloud Logs service. For more information, see [Granting IAM permissions for ingestion](https://cloud.ibm.com/docs/cloud-logs?topic=cloud-logs-iam-ingestion-permissions&format=markdown). Choose one of the following options: ### Option 1: Authentication using a trusted profile {: #agent-helm-os-deploy-step1-tp} Create a Trusted Profile. For more information, see [Generating a Trusted Profile for ingestion](https://cloud.ibm.com/docs/cloud-logs?topic=cloud-logs-iam-ingestion-trusted-profile&format=markdown). ### Option 2: Authentication using a service ID API key {: #agent-helm-os-deploy-step1-key} Generate an API Key for service ID authentication. For more information, see [Generating an API Key for ingestion](https://cloud.ibm.com/docs/cloud-logs?topic=cloud-logs-iam-ingestion-serviceid-api-key&format=markdown). ## Step 2. Configuring the Helm chart values file for the Logging agent {: #agent-helm-os-deploy-step2} Complete the following steps: 1. Create a file named `logs-values.yaml` with the following content: This file contains the configurations that are specific to your deployment.{: note} ```yaml metadata: name: "logs-agent" image: version: "1.6.1" # required clusterName: "ENTER_CLUSTER_NAME" # Enter the name of your cluster. This information is used to improve the metadata and help with your filtering. env: # ingestionHost is a required field. For example: # ingestionHost: ".ingress.us-east.logs.cloud.ibm.com" ingestionHost: "" # required # If you are using private CSE proxy, then use port number "3443" # If you are using private VPE Gateway, then use port number "443" # If you are using the public endpoint, then use port number "443" ingestionPort: "" # required iamMode: "TrustedProfile" # trustedProfileID - trusted profile id - required for iam trusted profile mode trustedProfileID: "Profile-yyyyyyyy-xxxx-xxxx-yyyy-zzzzzzzzzzzz" # required if iamMode is set to TrustedProfile scc: # true here enables creation of Security Context Constraints in Openshift create: true ``` {: codeblock} 2. Update the fields in the yaml file with values specific to your environment. | Field Name | Description | |------------|-------------| | `image.version` | The version of the agent to be deployed [see Step 1](#agent-helm-os-deploy-step1) | | `clusterName` | The name of the cluster - this will introduce the tag `kubernetes.cluster_name` into all log lines | | `env.ingestionHost` | The public or private ingress endpoint for the IBM Cloud Logs instance to receive the logs | | `env.ingestionPort` | The ingress endpoint port \n Public ingress endpoint = `443` \n Private ingress endpoint(VPE) = `443` \n Private ingress endpoint(CSE) = `3443` | | `env.iamMode` | `TrustedProfile` or `IAMAPIKey` based on the authentication method chosen in [Step 1](#agent-helm-os-deploy-step1) | | `env.trustedProfileID` | If `iamMode` is `TrustedProfile` then provide the Trusted Profile ID, otherwise this is not required (for example: `Profile-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` ). | | `env.iamEnvironment` | Dictates the correct IAM authentication endpoint. Valid values are `Production`, `PrivateProduction`, or `Custom`. If omitted, the default value is `Production`.| | `env.iamHost` | If `iamEnvironment` is `Custom`, then provide the IAM host (for example: `private.eu-de.iam.cloud.ibm.com`), otherwise this is not required. | | `scc.create` | Set to `true` in order to create the security constraints in Openshift | {: caption="Helm chart required parameters" caption-side="bottom"} ## Step 3. Install the Helm chart {: #agent-helm-os-deploy-deploy-step3a} If you are using the `iamMode` as `IAMAPIKey` then the apikey needs to be present in a Kubernetes secret named `logs-agent` with the key name `IAM_API_KEY`. The secret can be created using the Helm chart by including the `--set secret.iamAPIKey=` option when running the helm install. If the secret has been created manually or if you are using `iamMode=TrustedProfile` then do not include this option. {: important} Complete the following steps: 1. Log in to the cluster. Red Hat OpenShift on IBM Cloud is integrated with IBM Cloud Identity and Access Management (IAM). With IAM, you can authenticate users and services by using their IAM identities and authorize actions with access roles and policies. When you authenticate as a user through the Red Hat OpenShift console, your IAM identity is used to generate a Red Hat OpenShift login token that you can use to log in to the command line. You can automate logging in to your cluster by creating an IAM API key or service ID to use for the `oc login` command. For more information, see [Accessing Red Hat OpenShift clusters](https://cloud.ibm.com/docs/openshift?topic=openshift-access_cluster&format=markdown#access_automation). For example, complete the steps in [Using a service ID to log in to clusters](https://cloud.ibm.com/docs/openshift?topic=openshift-access_cluster&format=markdown#access_service_id) to log in to your cluster. 2. Perform a Helm dry run to see the resources that will be created by the Helm chart. If you are using the `iamMode`=`TrustedProfile` then the complete command is: ```sh helm install --dry-run oci://icr.io/ibm-observe/logs-agent-helm --version --values /logs-values.yaml -n ibm-observe --create-namespace ``` {: codeblock} If you are using the `iamMode`=`IAMAPIKey` then the complete command is: ```sh helm install --dry-run oci://icr.io/ibm-observe/logs-agent-helm --version --values /logs-values.yaml -n ibm-observe --create-namespace --set secret.iamAPIKey= --hide-secret ``` {: codeblock} where: - `` is the name of the Helm installation (`logs-agent`) - `` is the version of the helm chart. The Helm chart version should match the agent image version. For more information, see [Helm chart versions](https://cloud.ibm.com/docs/cloud-logs?topic=cloud-logs-agent-helm-template-clusters&format=markdown). - `` is the directory path where the `logs-values.yaml` file is located. - `` is the IAM apikey associated with the ServiceID [setup in Step 1](#agent-helm-os-deploy-step1) - Add `--hide-secret` to hide the API key from showing in the output data after the command runs. If you would like to inspect the helm chart contents locally, you can download the helm chart to your computer using the command: `helm pull oci://icr.io/ibm-observe/logs-agent-helm --version `. The downloaded tgz file contains the chart contents. {: tip} For example, you can run the following command from the directory where the `logs-values.yaml` file is available: ```sh helm install logs-agent --dry-run oci://icr.io/ibm-observe/logs-agent-helm --version 1.6.0 --values ./logs-values.yaml -n ibm-observe --create-namespace --set secret.iamAPIKey= --hide-secret ``` {: codeblock} 4. Once the resources to be created are verified, then run the Helm install without the `--dry-run` option If you are using the `iamMode`=`TrustedProfile` then the complete command is: ```sh helm install oci://icr.io/ibm-observe/logs-agent-helm --version --values /logs-values.yaml -n ibm-observe --create-namespace ``` {: codeblock} If you are using the `iamMode`=`IAMAPIKey` then the complete command is: ```sh helm install oci://icr.io/ibm-observe/logs-agent-helm --version --values /logs-values.yaml -n ibm-observe --create-namespace --set secret.iamAPIKey= ``` {: codeblock} where: - `` is the name of the Helm installation (`logs-agent`) - `` is the version of the helm chart. The Helm chart version should match the agent image version. For more information, see [Helm chart versions](https://cloud.ibm.com/docs/cloud-logs?topic=cloud-logs-agent-helm-template-clusters&format=markdown). - `` is the directory path where the `logs-values.yaml` file is located. - `` is the IAM apikey associated with the ServiceID [setup in Step 1](#agent-helm-os-deploy-step1) ## Step 4. Verify the agent is successfully deployed {: #agent-helm-os-deploy-deploy-step4} When the agent is deployed, check the following resources are created: - The `ibm-observe` namespace. To list the namespaces in the cluster, run the following command: ```sh oc get namespace ``` {: codeblock} You can also run the following command to search for the `ibm-observe` namespace: ```sh oc get namespace | grep ibm-observe ``` {: codeblock} - A config map `logs-agent` in the namespace `ibm-observe`. Run the following command to view the agent config details. ```sh oc get configmap logs-agent -n ibm-observe ``` {: codeblock} You can also use the following command: ```sh oc describe configmaps logs-agent -n ibm-observe ``` {: codeblock} - A daemonset `logs-agent` in the namespace `ibm-observe`. Run the following command to view the daemonset: ```sh oc get ds -n ibm-observe ``` {: codeblock} - Retrieve the list of agent pods by using the following command: ```sh oc get pods -n ibm-observe -o wide ``` {: pre} ```text NAME READY STATUS RESTARTS AGE IP NODE NOMINATED NODE READINESS GATES logs-agent-4lwvt 1/1 Running 0 2d5h 172.17.61.181 192.168.16.4 logs-agent-g7z87 1/1 Running 0 2d5h 172.17.0.48 192.168.32.4 logs-agent-nw56s 1/1 Running 0 2d5h 172.17.32.232 192.168.0.10 ``` {: screen} The `READY` column shows `1/1` for all pods, with a `STATUS` of `Running`. Verify that an agent pod is ready for each node in your cluster. To check how many workers are available in your cluster, you can run the following command: ```sh oc get nodes ``` {: codeblock} ```text NAME STATUS ROLES AGE VERSION 192.168.0.10 Ready master,worker 8d v1.20.0+558d959 192.168.32.4 Ready master,worker 8d v1.20.0+558d959 192.168.16.4 Ready master,worker 8d v1.20.0+558d959 ``` {: screen} The number of items in each of these two lists need to be the same, and you can match the IP addresses in the node names with the values in the `NODE` column of the pod listing. If your nodes are not named by their IP, you can append the `-o wide` option and compare the values in the `INTERNAL-IP` column instead. To view the logs of a pod, run `oc logs > -n ibm-observe`{: tip} ## Step 5. Verify logs are being delivered to your target destination {: #agent-helm-os-deploy-deploy-step5} Complete the following steps: 1. [Go to the web UI for your IBM Cloud Logs instance.](https://cloud.ibm.com/docs/cloud-logs?topic=cloud-logs-instance-launch&format=markdown). 2. When your agent is correctly configured, you can see logs through the default dashboard view. The Logging agent tags log records with a kubernetes object that includes the cluster name. ```text kubernetes.cluster_name: ``` {: codeblock} You can run the query `kubernetes.cluster_name:` in your IBM Cloud Logs instance to search for logs that are generated by your cluster.