--- name: cloud-logs-agent-helm-kube-deploy title: Deploying the Logging agent for Kubernetes clusters using a Helm chart description: You can use a Helm chart to deploy the Logging agent v1.6.x to collect and route infrastructure and application logs from a Kubernetes 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 for Kubernetes clusters using a Helm chart {: #agent-helm-kube-deploy} You can use a Helm chart to deploy the Logging agent v1.6.x to collect and route infrastructure and application logs from a Kubernetes 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 Kubernetes 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 Kubernetes cluster: ## Before you begin {: #agent-helm-kube-deploy-prereqs} - Make sure you have access to Kubernetes 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 Kubernetes CLI to manage the cluster by using `kubectl` commands. [Learn more](https://cloud.ibm.com/docs/containers?topic=containers-cli-install&format=markdown). - 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-kube-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-kube-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-kube-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-kube-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 ``` {: 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](https://cloud.ibm.com/docs/cloud-logs?topic=cloud-logs-agent-helm-kube-deploy&format=markdown#agent-helm-kube-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](https://cloud.ibm.com/docs/cloud-logs?topic=cloud-logs-agent-helm-kube-deploy&format=markdown#agent-helm-kube-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. | {: caption="Helm chart required parameters" caption-side="bottom"} ## Step 3. Install the Helm chart {: #agent-helm-kube-deploy-deploy-step3} 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. For more information, see [Access your cluster](https://cloud.ibm.com/docs/containers?topic=containers-access_cluster&format=markdown). 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](https://cloud.ibm.com/docs/cloud-logs?topic=cloud-logs-agent-helm-kube-deploy&format=markdown#agent-helm-kube-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 ``` {: screen} 3. 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](https://cloud.ibm.com/docs/cloud-logs?topic=cloud-logs-agent-helm-kube-deploy&format=markdown#agent-helm-kube-deploy-step1) ## Step 4. Verify the agent is successfully deployed {: #agent-helm-kube-deploy-deploy-step4} When the agent is deployed, check the following resources are created: - The `ibm-observe` namespace. Run the following command to list the namespaces in the cluster and check that the `logger-agent` shows with status active. ```sh kubectl get namespace ``` {: codeblock} - A config map `logs-agent` in the namespace `ibm-observe`. Run the following command to view the agent config details. ```sh kubectl get configmap logs-agent -n ibm-observe ``` {: codeblock} You can also use: ```sh kubectl 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 kubectl get ds -n ibm-observe ``` {: codeblock} - Verify the agents are started: ```sh kubectl -n ibm-observe get ds logs-agent ``` {: codeblock} - Retrieve the list of agent pods by using the following command: ```sh kubectl get pods -n ibm-observe -o wide ``` {: codeblock} ```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 kubectl 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 `kubectl logs > -n ibm-observe` {: tip} To check the helm chart deployed, run `helm list -n ibm-observe` {: tip} ## Step 5. Verify logs are being delivered to your target destination {: #agent-helm-kube-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.