Upgrade an integration

You can upgrade a self-hosted Ocean integration by changing its container image version in your existing deployment. Review the integration's release notes first, and keep your existing connection settings and integration identifier.

The examples below use the custom integration version 0.6.158 and Ocean Helm chart 0.24.1. Replace the release name, namespace, integration type, and versions with those of your deployment.

For integrations hosted by Port, contact your Port support representative to confirm the installed version and available upgrade options.

Choose an integration version

Ocean core, integration images, and the Helm chart have separate versions:

Version	What it controls
Integration image tag	The integration application and its packaged Ocean core dependency. Select a release from the integration's changelog in the Ocean repository.
Helm chart version	The Kubernetes deployment templates. Select a chart release from the Helm chart repository.
Ocean core version	The shared Python framework packaged in the integration image. You do not need to update Python dependencies separately when deploying a published image.

Pin an integration image tag when you need a repeatable deployment. An unpinned Helm integration.version defaults to latest in chart 0.24.1.

Upgrade with Helm

In chart 0.24.1, integration.version selects the tag of the default image, ghcr.io/port-labs/port-ocean-<integration.type>:<integration.version>.

If you configured the image value, it overrides that default image name and tag. image is a string such as port-ocean-custom:0.6.158, not an object with a tag field. Use imageRegistry separately for the registry prefix.

1. Check the installed release and chart version:

   RELEASE_NAME=ocean-custom
   NAMESPACE=port
   
   helm list --namespace "$NAMESPACE"
   helm get values "$RELEASE_NAME" --namespace "$NAMESPACE" --output yaml

2. Review your integration's release notes and the chart's values before choosing the target versions. Export your current values so you can keep your connection settings:

   helm get values "$RELEASE_NAME" --namespace "$NAMESPACE" --output yaml > ocean-values.yaml

   Store this file securely because it may contain credentials. If it contains an image override, update that string to the desired image and tag, or remove the override to use integration.version.

3. Upgrade the existing release using the saved values and an explicit integration version:

   CHART_VERSION=0.24.1
   INTEGRATION_VERSION=0.6.158
   
   helm repo add port-labs https://port-labs.github.io/helm-charts
   helm repo update port-labs
   helm upgrade "$RELEASE_NAME" port-labs/port-ocean \
     --namespace "$NAMESPACE" \
     --version "$CHART_VERSION" \
     --values ocean-values.yaml \
     --set-string integration.version="$INTEGRATION_VERSION"

4. Verify the release and the image configured on its deployment:

   helm status "$RELEASE_NAME" --namespace "$NAMESPACE"
   kubectl get deployments --namespace "$NAMESPACE" \
     --selector "app.kubernetes.io/instance=$RELEASE_NAME" \
     --output 'jsonpath={range .items[*].spec.template.spec.containers[*]}{.image}{"\n"}{end}'

   Confirm that the image has the tag you selected. Check the integration's logs and sync status for startup or resync errors.

Upgrade with Docker

Update the image tag in your existing Docker deployment configuration. Pulling an image alone does not replace a running container.

For Docker Compose, first set the service's image to the desired tag, such as ghcr.io/port-labs/port-ocean-custom:0.6.158. Then pull and recreate that service using its existing configuration:

SERVICE_NAME=ocean-custom

docker compose pull "$SERVICE_NAME"
docker compose up --detach --no-deps "$SERVICE_NAME"
docker compose images "$SERVICE_NAME"

If you originally used docker run, recreate the container using the installation command for your integration, retaining its environment variables, mounted files, network settings, and integration identifier. Change the image tag in that command to the version you selected.

Upgrade through infrastructure as code

If Terraform or Pulumi manages your deployment, update the integration resource's version in your existing configuration. Review the planned changes before applying them, so the next infrastructure run does not restore an older image.

See the integration resource settings for Terraform and Pulumi.