Before you begin

• Make sure you have access to Kubernetes cluster with permissions to create namespaces and deploy the agent.

• Take a copy of the current config map for the logging agent. Run: kubectl get cm logs-agent -n ibm-observe -o yaml > logging-agent-backup-cm.yaml

• 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 Kubernetes clusters by using kubectl commands. Learn more.

  • The Openshift CLI to manage OpenShift clusters from the command line. Learn more.

• Read about the Logging agent.

• Check the agent versions that are available. For more information, see Checking the available agent versions. 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. Update the Helm chart values file for the Logging agent

Complete the following steps to modify the Helm chart with the agent version that you plan to deploy:

1. Update the file named logs-values.yaml that you used to deploy the agent with the following content:

   The logs-values.yaml file contains the configurations that are specific to your deployment.

   If you do not have the logs-values.yaml file that you used to deploy the agent, create one based on the current configmap configuration of the agent.

   metadata:
     name: "logs-agent"
   image:
     version: "1.6.1"  # Modify the agent version and enter the version that you want to deploy
   
   clusterName: "ENTER_CLUSTER_NAME"     # Enter the name of your cluster. This information is used to improve the metadata and help with your filtering.
   
   additionalMetadata: # add additional metadata, for example:
     region: au-syd
     env: production
     logs-agent-version: 1.6.1     # Enter the agent version that you want to deploy
   
   env:
     # ingestionHost is a required field. For example:
     # ingestionHost: "<logs instance>.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: "" # required if iamMode is set to TrustedProfile
   
   

Step 2. Update the agent

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=<your 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.

Complete the following steps:

1. Log in to the cluster. For more information, see Access your cluster.

2. Update the agent.

   If you have installed a previous version of the Logging agent and have updated the agent configuration by modifying the config map directly in the cluster, make a copy of your config map from the cluster before running the helm upgrade command. When the Logging agent is updated, any changes made to the config map will be overwritten.

   If you are using the iamMode=TrustedProfile then the complete command is:

   helm upgrade <install-name> oci://icr.io/ibm-observe/logs-agent-helm --version <chart-version> --values <PATH>/logs-values.yaml -n ibm-observe
   

   If you are using the iamMode=IAMAPIKey then the complete command is:

   helm upgrade <install-name> oci://icr.io/ibm-observe/logs-agent-helm --version <chart-version> --values <PATH>/logs-values.yaml -n ibm-observe --set secret.iamAPIKey=<APIKey-value>
   

   where:

   • <install-name> is the name of the Helm installation (logs-agent). You can run the following command to get the install name: helm list -n ibm-observe
   • <chart-version> is the version of the helm chart. The Helm chart version should match the agent image version. For more information, see Helm chart versions.
   • <PATH> is the directory path where the logs-values.yaml file is located.
   • <APIKey-value> is the IAM apikey associated with the ServiceID.

   For example, you can run the following command from the directory where the logs-values.yaml file is available:

   helm upgrade logs-agent oci://icr.io/ibm-observe/logs-agent-helm --version 1.5.0 --values ./logs-values.yaml -n ibm-observe --set secret.iamAPIKey=<secret>
   

   To see installed agent name and chart version you can run helm list -n NAMESPACE.

3. Restart the agent pods.

   For Kubernetes clusters, run:

   kubectl -n ibm-observe rollout restart ds/logs-agent
   

   For OpenShift clusters, run:

   oc -n ibm-observe rollout restart ds/logs-agent
   

4. Check that all pods have restarted, in running status, and not reporting errors.

   For Kubernetes clusters, run:

   kubectl get pods -n ibm-observe
   

   For OpenShift clusters, run:

   oc get pods -n ibm-observe
   

Step 3. Verify logs are being delivered to your target destination

Complete the following steps:

1. Go to the web UI for your IBM Cloud Logs instance..

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.

   kubernetes.cluster_name:<CLUSTER_NAME>
   

   You can run the query kubernetes.cluster_name:<YOUR_CLUSTER_NAME> in your IBM Cloud Logs instance to search for logs that are generated by your cluster.