CNE GCP Ready: Adding OSGi Modules or Client Extensions With Overlays

The Cloud Native Experience (CNE) toolkit uses overlays to customize standard Liferay deployments.

Upload custom files (such as OSGi modules, client extensions, configuration files, or site initializers) to a dedicated Google Cloud Storage bucket and configure your environment to apply them during pod startup.

This approach avoids custom Liferay image builds, applies changes on top of the standard container, and is fully managed through GitOps.

CNE supports two overlay workflows:

• Manual overlays
• Automated overlays with GitOps and CI

How Overlays Work

When overlays are enabled, an init container downloads files from the overlay bucket during pod startup and copies them into the Liferay runtime filesystem.

Overlay files are layered into the container at startup time and are not persisted in a separate volume.

The overlay feature is disabled by default and must be enabled in liferay.yaml.

Manual Overlay Workflow

Locate the Overlay Bucket

Open the Google Cloud Console and navigate to Cloud Storage → Buckets.

Locate the bucket associated with your environment. Overlay buckets typically end with -overlay.

Upload Customizations

Create a top-level folder in the bucket and upload your customizations.

Example:

overlay_test_1/
└── osgi/
   └── client-extensions/

Configure the Overlay

In your environment-specific liferay.yaml, configure the overlay.

liferay-default:
   overlay:
      copy:
         - from: overlay_test_1/osgi/client-extensions/*
           into: osgi/client-extensions
      enabled: true
      type: gcs

Overlay Configuration Reference

Property	Description
enabled: true	Enables overlay processing during pod startup
type: gcs	Configures the overlay init container to use Google Cloud Storage
copy.from	Source path in the overlay bucket
copy.into	Destination path inside the Liferay container

Commit and push the configuration change to your GitOps repository.

Argo CD synchronizes the environment and applies the overlay configuration.

Automated Overlay Workflow (GitOps and CI)

Locate the Overlay Bucket

1. Switch to the environment namespace.

   kubens liferay-<projectId>-<environmentId>
   

2. List the overlay bucket resource.

   kubectl get buckets.storage.gcp.m.upbound.io --selector component=overlay
   

   Example output:

   NAME                                    SYNCED   READY   EXTERNAL-NAME                           AGE
   my-deployment-overlay-able-dev-2225eb   True     True    my-deployment-overlay-able-dev-2225eb   22h
   

Use the EXTERNAL-NAME value as the bucket name.

Configure CI Authentication

Unlike AWS environments, GCP environments do not provision CI upload credentials for overlays automatically.

Configure authentication separately using Workload Identity Federation (WIF).

1. Create a Google Service Account for CI uploads.

   liferay-ci-uploader@PROJECT_ID.iam.gserviceaccount.com
   

2. Grant the service account permission to upload overlay objects.

   gcloud storage buckets add-iam-policy-binding gs://${GCS_BUCKET_NAME} \
      --member="serviceAccount:liferay-ci-uploader@${PROJECT_ID}.iam.gserviceaccount.com" \
      --role="roles/storage.objectCreator"
   

3. Configure Workload Identity Federation for your CI provider.

For more information, see Workload Identity Federation with GitHub Actions.

Build and Upload Customizations

Configure the following GitHub Actions secrets:

Secret	Description
GCP_WIF_PROVIDER	Full resource name of the Workload Identity Provider
GCP_CI_UPLOADER_SA	Email address of the CI uploader Google Service Account
GCS_BUCKET_NAME	Overlay bucket name without the gs:// prefix

Example workflow:

name: CNE Workspace Build

on: [push]

permissions:
   contents: read
   id-token: write

jobs:
   build:
      runs-on: ubuntu-latest

      steps:
         - uses: actions/checkout@v4

         - name: Set up JDK 11
           uses: actions/setup-java@v4
           with:
              java-version: '11'
              distribution: 'adopt'

         - name: Build with Gradle
           run: cd workspace/ && ./gradlew build deploy

         - name: Authenticate to GCP
           uses: google-github-actions/auth@v2
           with:
              workload_identity_provider: ${{ secrets.GCP_WIF_PROVIDER }}
              service_account: ${{ secrets.GCP_CI_UPLOADER_SA }}

         - name: Upload customizations to GCS bucket
           run: |
              gcloud storage cp \
                 --recursive \
                 workspace/bundles/osgi/ \
                 gs://${{ secrets.GCS_BUCKET_NAME }}/workspace_build_${{ github.run_number }}/osgi/

Configure the Overlay

In liferay/projects/<projectId>/environments/<environmentId>/liferay.yaml, configure the overlay to use the uploaded artifacts:

liferay-default:
   overlay:
      copy:
         - from: "workspace_build_1/osgi/client-extensions/*"
           into: osgi/client-extensions
      enabled: true
      type: gcs

Commit and push the change to your GitOps repository.

Argo CD synchronizes the environment and applies the overlay configuration.

Verify the Overlay Deployment

Check the overlay init container logs:

kubectl logs liferay-default-0 -c liferay-overlay

Example output:

Copying from ":gcs:my-deployment-overlay-able-dev-2225eb/workspace_build_1/osgi/client-extensions" to "/temp/osgi/client-extensions".
...
Copy completed successfully.