Upgrade your OCI log forwarding integration

The OCI log forwarding integration sends logs from your Oracle Cloud Infrastructure (OCI) tenancy to New Relic. Over time, New Relic releases new versions of the integration that add features, fix problems, and deliver security updates. If logs stop arriving or you run into other problems with your existing integration, a newer version may contain the fix. Because the integration runs in your own tenancy, you receive new versions by upgrading what you've deployed. This guide walks you through that process:

Identify which setup you're on.
Move from the previous setup to the current one, if needed.
Upgrade using Resource Manager, Terraform, or manual setup.
Verify that logs are still arriving.

To set up forwarding for the first time, see Install and configure OCI log forwarding.

When to upgrade

Upgrading isn't required while your logs are flowing. Read the release notes for each new version on the oci-log-integration releases page to decide whether a release matters to you. Check them for breaking changes in particular, because you may need to act on those.

Identify your setup

Your deployment uses one of two setups. Check the settings on your Resource Manager stack or Terraform module:

Current setup, with a Function image setting: The integration copies the function image from Docker Hub into a private Container Registry repository in your own tenancy when you apply, and the function runs from that copy. Because your function doesn't depend on a New Relic-hosted registry at runtime, its availability isn't tied to that registry. The integration uses Docker Hub only during the apply. Versions can be pinned.
Previous setup, with a New Relic Owned Registry setting: The function pulls directly from a New Relic-owned registry, at the version you set, instead of from a copy in your own tenancy. New Relic has retired this setting.

If you're on the previous setup, make a one-time move to the current setup first. After that, every upgrade follows the regular upgrade steps.

Understand the function and template

The integration has two parts. They're versioned and released independently, and a release can change either or both:

Log-forwarder function: The code that sends logs to New Relic. New Relic publishes it to Docker Hub as docker.io/newrelic/oci-log-forwarder and names each release function-<version> on the oci-log-integration releases page.
Integration template: The configuration around the function, which is the Resource Manager stack and its variables, or the Terraform module. Template releases use plain version numbers on the same releases page and include the oci-log-integration.zip file. Terraform module versions are the terraform-provider-newrelic release tags.

How each part updates depends on your method:

Resource Manager and Terraform refresh the function for you. Every apply checks which image the latest tag points to on Docker Hub and brings in the newer one.
A newer template is a deliberate step. Update the template only when a release changes it, and update the function at the same time. That keeps your deployment in the combination New Relic tested for the release. Function releases stay compatible with the templates already in use, so you can take a newer function before a newer template.
Manual setups update nothing automatically. You choose the version and copy the image yourself.

Before you start

Before you upgrade:

Make sure you can edit the Resource Manager stack, the Terraform configuration, or the Functions application that runs your integration.
Note the version you're running now, and compare it with the latest release: the Function image value or image tag, and the ?ref= value on your Terraform modules.

Move from the previous setup to the current setup

This is a one-time migration, not a version bump.

What changes. Your configuration gains a Function image setting with the full image reference, plus optional Container Registry username and auth token settings. New Relic has retired New Relic Owned Registry, and it has no effect. On the first apply, the integration creates the private Container Registry repository, named newrelic-logs/oci-log-forwarder (or newrelic-logs-tf/oci-log-forwarder on Terraform), and copies the function image into it.

What to check first. Whatever runs the apply needs outbound access to Docker Hub and to your own tenancy's Container Registry, on top of the OCI endpoints it already reaches. The integration also needs a Container Registry credential to push the image. If you leave the auth token setting empty, it creates one for the user running the apply and reuses it on later applies.

Importante

OCI limits how many auth tokens each user can have, currently two. If the user running the apply already has the maximum and you leave the auth token setting empty, the apply fails with an error asking for an existing token. Delete an unused token first, or enter an existing token and its username in the auth token and username settings. Check the current limit in your OCI User Settings.

Follow these steps to move your stack to the current setup.

Download oci-log-integration.zip from the latest template release on the releases page.
Edit your logs stack and upload the zip as the new stack configuration, replacing the existing one.
On the variables page, leave Function image at its default unless you want to hold a specific version. Leave the Container Registry username and auth token empty (see the note above).
Save the stack and run Plan. The output should show that the apply creates the new Container Registry repository and updates the function.
Run Apply. This first apply takes longer than usual because it copies the function image into your tenancy.

Follow these steps to move your modules to the current setup. For the current reference example, see the Terraform Registry OCI guide.

Move ?ref= on both module blocks to v3.101.4 or later, the first release in which the module copies the function image into your own Container Registry. The version in this example is only a sample, so use the release you want.
```
module "oci_policy_setup" {
  source = "https://github.com/newrelic/terraform-provider-newrelic/tree/main/examples/modules/cloud-integrations/oci/policy-setup?ref=v3.101.4"
}

module "oci_logs_integration" {
  source = "https://github.com/newrelic/terraform-provider-newrelic/tree/main/examples/modules/cloud-integrations/oci/logs-integration?ref=v3.101.4"
}
```
Remove the image_version variable from your configuration.
Add user_ocid if it isn't already set. The module uses it to create the Container Registry credential that pushes the image.
From the policy module's directory, run terraform init -upgrade, terraform plan, and terraform apply. Do this first because the policy module can contain permission changes the logs module depends on.
From the logs module's directory, run the same three commands.

The guided setup in New Relic shows the current manual steps, so use it to compare against your tenancy and spot anything new, including changes to the IAM policy or dynamic group.

Create a Container Registry repository in your tenancy for the function image, for example newrelic-logs/oci-log-forwarder.
Pull the version you want from docker.io/newrelic/oci-log-forwarder, then tag and push it to that repository under the same version number.
Edit your logs function and set its image to the version you pushed.

Upgrade a deployment on the current setup

Use these steps if your stack or module has a Function image setting. Choose the method you used to set up the integration.

To pick up a newer function, run Plan and then Apply on your stack.

When a release changes the template, also do the following:

Download oci-log-integration.zip from the template release you want on the releases page. Resource Manager accepts a local file, not a URL.
Edit your logs stack and upload the zip as the new stack configuration, replacing the existing one.
Keep your existing variable values for your New Relic account, region, payload, and networking.
Save the stack and run Plan. Read the output to confirm the changes are what you expect.
Run Apply and wait for the job to succeed.
To hold the function on a specific version, set Function image to that version's full reference, for example docker.io/newrelic/oci-log-forwarder:1.3.0. Change the payload setting only if you've added log groups or compartments to instrument.

To pick up a newer function, run terraform apply.

To take a newer module, move both module blocks to the same release and apply them in order. Before you do, compare your module blocks against the current reference example in the Terraform Registry OCI guide. Adopt any differences, such as new variables, changed defaults, or a newer ?ref=.

module "oci_policy_setup" {
  source = "https://github.com/newrelic/terraform-provider-newrelic/tree/main/examples/modules/cloud-integrations/oci/policy-setup?ref=v3.101.6"
}

module "oci_logs_integration" {
  source = "https://github.com/newrelic/terraform-provider-newrelic/tree/main/examples/modules/cloud-integrations/oci/logs-integration?ref=v3.101.6"
}

To apply the upgrade:

Set ?ref= to the same release on both module blocks. This is the query parameter at the end of each module's source URL, and v3.101.6 is only a sample. Use v3.101.4 or later.
Check your New Relic Terraform provider version with terraform version, which lists the resolved provider version (for example, + provider registry.terraform.io/newrelic/newrelic v3.99.2). The current template needs v3.99.2 or later, and an older provider fails the apply rather than warning you.
From the policy module's directory, run the following commands first, because it can contain permission changes the logs module depends on.
bash
```
$terraform init -upgrade
$terraform plan
$terraform apply
```
From the logs module's directory, run the same three commands.

Choose a version, copy that image into your own Container Registry, and point your function at the copy.

Pick the version from the releases page, then confirm the matching tag on the Docker Hub tags page.
Pull that version, then tag and push it to your Container Registry repository under the same version number. Don't tag your copy latest. Nothing keeps it in sync, and a version number records exactly what you deployed.
Edit your logs function and set its image to the version you pushed.

Verify after upgrading

Confirm logs are still arriving within a few minutes of the upgrade:

SELECT count(*) FROM Log WHERE instrumentation.provider = 'oci' SINCE 10 minutes ago

If counts drop to zero, check the function's execution logs in the OCI Console.

A brief slowdown on the first invocation after an upgrade is normal while the function pulls the new image. To confirm which version you landed on, check the image tag in your Container Registry repository.

Install and configure OCI log forwarding: Set up OCI log forwarding for the first time.
Monitor your OCI log forwarder: Enable self-observability metrics on the log forwarder function.
Troubleshooting: Fixes for not seeing data during setup.

Upgrade your OCI log forwarding integration

When to upgrade .css-21sua1{background:none;border:none;width:0;padding:0;}