Skip to content

Image Build Options

There are three options you can use to build and manage container images for services in Coherence:

  • The built-in build step (default and recommended)
  • Externally built images
  • CNC template customization

This guide outlines the benefits and methods of each approach.

The built-in build step

The easiest and most integrated option is to use Coherence's built-in build pipeline. This uses the default Coherence image build process, which:

  • Occurs in your connected cloud account as part of the Coherence build pipeline.
  • Automatically implements best practices, such as using a multi-stage Docker build cache.
  • Reduces vendor complexity by using a managed registry in the same cloud account used for the rest of the build pipeline.
  • Offers automatic containerization with Nixpacks if no Dockerfile is defined for the service.

You can configure Dockerfile, Docker build context, and Nixpacks configuration options when setting up a service, including additional configuration files in your repo when necessary. When using Nixpacks, you can also define behavior using the Nixpacks environment variable configuration options.

How to use the built-in build step

  1. In the Services tab on your environment homepage, click New service, and select a service provider under the Container header.
  2. In the New container service form, select Repository as the Container Source.

Coherence will automatically set up the build pipeline in your cloud account.

Benefits

The built-in build step offers seamless integration with the Coherence workflow.

Services containers that use the build step way are optimized for performance and security.

Using cloud-native services reduces the complexity and number of vendors in your stack.

Externally built images

Coherence also allows you to build service containers using pre-existing images from public and private sources.

You can build various container image types in Coherence, including public images (such as images from open-source projects on Docker Hub), images built in your external CI/CD pipeline, or images that have been manually pushed to a private registry.

How to use externally built images

  1. In the Services tab on your environment homepage, click New service, and select a service provider under the Container header.

  2. In the New container service form, select Existing Image as the Container Source and choose a Tag Source:

    • Static uses the same tag on every deployment until manually updated in the service configuration form or cnc.yml. This is the best option for deploying third-party-built containers.
    • GitHub uses the SHA from the repo push to GitHub as the image tag.
    • Other allows you to specify a custom tag for each deployment via the New deployment form or CLI.

Considerations

It's easiest to use the Coherence-managed registry in AWS or GCP for each collection. This registry is created when you provision the infrastructure for a collection.

  • If you've already provisioned the infrastructure for your collection, the Managed Image Registry URL will be displayed in the Edit service form. Use this value as the image host for your image source. Copy Managed Image Registry URL to the Image form field to configure your service. other-container-source-mode
  • If you haven't yet provisioned the infrastructure for your collection, you'll need to use a placeholder value in the Image field of the Edit service form until you provision the infrastructure. You will need to come back and edit the service to deploy from that image instead of your placeholder. You only need to provision once per collection to complete this step.

You'll need to set up your image build script to push the built images to this registry with the appropriate tags.

  • Popular CI systems have plenty of examples of pushing to ECR in AWS or Artifact Registry in GCP, but you can contact Coherence Support if you need help setting this up.

You can use another registry in the same cloud, instead of the Coherence-managed registry, if service credentials are authorized. However, the use of external registries is not yet a first-class supported feature in Coherence and may require CNC customization for authentication to pull the images.

Benefits

You have the flexibility to integrate external images with existing build processes.

You can use images built on other platforms (such as GitLab or Bitbucket) for managed infrastructure and deployment pipelines using the CLI from a cloud infrastructure provider.

Using an external image offers you manual control over image versions.

In some cases, external images improve build speed, especially for well-designed pipelines or services that use a persistent disk to cache Docker layers between builds.

Example configurations

Static tag option:

  • Service configuration: In the Edit container service form, Image is set to myimage and Tag is set to v1.0-ubuntu..
  • Result: Every pipeline deploys myimage:v1.0-ubuntu.

GitHub tag option:

  • Service configuration: In the Edit container service form, Image is set to us-east1-docker.pkg.dev/my-gcp-project/jad7d-prod-backend-1/api.
  • Result: On each push, the pipeline deploys us-east1-docker.pkg.dev/my-gcp-project/jad7d-prod-backend-1/api:GIT_PUSH_SHA.
  • Note: The New deployment form uses the branch-provided commit SHA as the tag.

Other tag option:

  • Service configuration: In the Edit container service form, Image is set to us-east1-docker.pkg.dev/my-gcp-project/jad7d-prod-backend-1/api
  • Result: Uses the tag provided in the New deployment form or CLI for each deployment, like us-east1-docker.pkg.dev/my-gcp-project/jad7d-prod-backend-1/api:PROVIDED_TAG.
  • Note: The branch is not used for this configuration in either the UI or the CLI.

CNC template customization

For advanced use cases, you can modify the build step using CNC template customization. You can create a custom CNC template by augmenting or replacing the default Coherence build script that runs in the CI pipeline.

  • See examples of CNC customization here.

This allows you to customize the build process while leveraging Coherence's environment-management and script-templating framework.

How to use CNC template customization

  1. In the Coherence dashboard, open Application settings and navigate to the CNC tab.
  2. Configure the CNC customization template location using the Repository and Folder Path fields below the Custom templates header.
  3. Navigate to your configured location.
  4. Modify the CNC build template for your service by using tools like Depot or Docker Build Cloud to implement custom build logic.
  5. Use the CNC template variables to access Coherence system information (for example, the environment name or service image tag).

Builds will now use your custom CNC build script rather than the script included in your CNC flavor.

Benefits

CNC template customization gives you maximum flexibility throughout the build process.

The build script can be used to integrate specialized build tools or workflows.

The process maintains a connection with the Coherence environment and deployment management.

Choosing the right option

  • For most users: The built-in build step provides the best balance between ease of use and integration.
  • For teams with existing CI/CD pipelines: Using externally built images allows teams to maintain their current build process while leveraging Coherence for deployment.
  • For advanced customization: CNC template customization offers the most flexibility but requires more setup and maintenance.

Regardless of the build method chosen, Coherence continues to manage the environment infrastructure and deployment pipelines, ensuring consistency across each application life cycle.