Custom Certificates are now available in Custom Assembly

The problem

Many enterprise container deployment starts with the same tedious ritual: manually injecting custom certificate authorities into images. Your security team manages the certificates in Venafi or another PKI tool, but it falls to developers to determine where to place them, which tools to run, and how to handle multi-certificate bundles that update-ca-certificates often chokes on. The result? Duplicated Dockerfile instructions across every image, forgotten certificates that break service-to-service communication, and expired certificates that bring production systems down. Your team shouldn't have to play this game of certificate whack-a-mole just to deploy secure containers.

Our solution

Today, we're announcing Custom Certificate support for Custom Assembly, enabling you to add your enterprise certificate authority certificates directly to your Chainguard Containers without writing Dockerfiles or managing complex build pipelines. Add certificates to your image configuration with chainctl, and we handle the rest: your certificates are automatically appended to all standard truststore locations.

How it works

Adding custom certificates to any image is as simple as adding the following section to the image configuration YAML file, as you would when customizing other parts of the image via Custom Assembly. For example, add this block to get started with certificates:

  certificates:
    additional:
      - name: enterprise-root-ca
        content: |
          -----BEGIN CERTIFICATE-----
          MIIFazCCA1OgAwIBAgIUe...
          -----END CERTIFICATE-----

For illustration, this is how an example full image configuration manifest could look:

contents:
  packages:
    - python-3.12
  certificates:
    additional:
      - name: enterprise-root-ca
        content: |
          -----BEGIN CERTIFICATE-----
          MIIFazCCA1OgAwIBAgIUe...
          -----END CERTIFICATE-----

It can be applied to a selected image with the following command:

$ chainctl images repos build apply --filename ./image-config.yaml my-image

Chainguard validates that you're providing certificates (not private keys), parses the details, and stores them as part of your image configuration. You'll see confirmation with the subject, serial number, and expiration date for each certificate added:

Image configuration changes:
Legend: + to add, ~ to change, - to remove

certificates.additional (+2, ~0, -0, final: 2):
  + Name: Entrust Root Certification Authority
      Subject: CN=Entrust Root Certification Authority,OU=www.entrust.net/CPS is incorporated by reference+OU=(c) 2006 Entrust\, Inc.,O=Entrust\, Inc.,C=US
      Serial: 1164660820
      Expires: 2026-11-27 20:53:42 UTC

  + Name: QuoVadis Root CA 2
      Subject: CN=QuoVadis Root CA 2,O=QuoVadis Limited,C=BM
      Serial: 1289
      Expires: 2031-11-24 18:23:33 UTC

Plan: 2 to add, 0 to change, 0 to remove

Applying modified build config to wolfi-base

Do you want to continue? [y,N]:

For more control, use chainctl images repos build edit to inline certificates directly in your configuration. That command will present you with an editor where you can manually edit the image configuration.

At build time, Chainguard appends your certificates to /etc/ssl/certs/ca-certificates.crt and writes individual files to /usr/local/share/ca-certificates/. Your certificates are ready for any application that uses the system truststore.

Why our approach is better

Unlike bolting certificates onto images through Dockerfile hacks or convoluted layer modifications, Custom Assembly treats your enterprise CAs as part of your image configuration. Certificates are inlined directly into your Custom Assembly definition and included in your image's provenance attestation, so you can trace exactly which certificates went into every build.

This approach eliminates an entire category of operational toil. For many organizations, the only reason they're rebuilding Chainguard Container images is to add certificates. With Custom Certificate support, that rebuild step disappears. Define your certificates once in your image configuration, and every build automatically includes them in all the right places.

We've also built in safeguards that protect you from common mistakes. Private keys are automatically rejected at configuration time, preventing accidental credential exposure. Certificates are validated to ensure they're properly formatted. And because certificates are defined in your image configuration rather than scattered across Dockerfiles, you have clear visibility into your container trust configuration.

What's coming next

This release is our first step toward simplifying certificate management for containerized workloads. We're exploring organization-level certificate defaults that would let you define certificates once and apply them across all images in your organization. We're also exploring ways to enhance audit logging and SBOM integration for organizations with more stringent compliance requirements.

We'd love to hear what certificate management challenges you're facing. Your feedback will help shape the direction of this feature next.

Get early access

Custom Certificate support is now available through our Beta program for Custom Assembly customers. Beta participants get hands-on experience with the feature while helping us refine it based on real-world usage.

Ready to eliminate certificate chaos from your container workflows? Contact your customer success team to enroll in Beta and be among the first to use Custom Certificates in your Chainguard Containers.