Using chainctl to Manage Custom Assembly Resources

Chainguard’s Custom Assembly is a tool that allows customers to create customized containers with extra packages added. This enables customers to reduce their risk exposure by creating container images that are tailored to their internal organization and application requirements while still having few-to-zero CVEs.

You can use chainctl, Chainguard’s command-line interface tool, to further customize your Custom Assembly builds and retrieve information about them. This guide provides an overview of the relevant chainctl commands and outlines how you can edit the configuration of Custom Assembly containers, as well as retrieve a list of a customized image’s builds and its build logs.

Editing a Customized Container Image

To edit one of your organization’s Custom Assembly container images, you can run the chainctl image repo build edit command:

chainctl image repo build edit --parent $ORGANIZATION --repo $CUSTOMIZED_CONTAINER

This example includes the --parent flag, which points to the name of your organization, and the --repo argument, which points to the name of your customized image. If you omit these arguments, chainctl will prompt you to select your organization and customized image interactively.

This command will open up a file with your machine’s default text editor. This file will contain a structure like the following:

contents:
  packages:
  - yarn
  - wget

Edit this file by adding or removing any packages you like. Then, save and close the file.

Before applying the change, chainctl will outline the changes you made and prompt you to confirm that you want to move forward with the change:

/tmp/3352123767.yaml (-deletion / +addition):

 contents:
   packages:
   - yarn
-  - wget
+  - bash
 
Applying build config to custom-node
Are you sure?
Do you want to continue? [y,N]:

Enter y to apply the changes.

Following that, you’ll be able to see the updated builds in the Chainguard Console, though it may take a few minutes for these changes to populate.

To edit a customized container image without any interactivity, you can use the apply subcommand. This method requires you to have a YAML file listing the desired packages, like the example created with this command:

cat > build.yaml <<EOF
contents:
  packages:
    - bash
    - curl
    - mysql
EOF

Then include this file in the apply command by adding the -f argument:

chainctl image repo build apply -f build.yaml --parent chainguard.edu --repo custom-assembly --yes

This command will again ask you to confirm that you want to apply the new configuration. To make this example completely declarative, this example includes --yes to automatically confirm the changes:

Applying build config to custom-assembly
  (*v1.CustomOverlay)(Inverse(protocmp.Transform, protocmp.Message{
  	"@type": s"chainguard.platform.registry.CustomOverlay",
  	"contents": protocmp.Message{
  		"@type": s"chainguard.platform.registry.ImageContents",
  		"packages": []string{
- 			"wolfi-base",
+ 			"bash",
- 			"go",
+ 			"curl",
+ 			"mysql",
  		},
  	},
  }))

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

This approach is useful in cases where you would prefer to avoid any kind of interactivity, as in a CI/CD or other automation system.

Retrieving Information about Custom Assembly Containers

You can also use the list subcommand to retrieve every one of a customized image’s builds from the past 24 hours:

chainctl image repo build list --parent $ORGANIZATION --repo $REPO

This command is useful for quickly determining which builds were successful or failed:

           START TIME           |        COMPLETION TIME        | RESULT  |                    TAGS                     
--------------------------------+-------------------------------+---------+---------------------------------------------
  Thu, 01 May 2025 10:10:40 PDT | Thu, 01 May 2025 10:10:45 PDT | Success | 20, 20.19, 20.19.1                          
  Thu, 01 May 2025 10:10:34 PDT | Thu, 01 May 2025 10:10:46 PDT | Success | 22-slim, 22.15-slim, 22.15.0-slim           
  Thu, 01 May 2025 10:10:33 PDT | Thu, 01 May 2025 10:10:41 PDT | Success | 23, 23.11, 23.11.0, latest                  

. . .

Lastly, you can also retrieve the logs for a given build with the logs subcommand:

chainctl image repo build logs --parent $ORGANIZATION --repo $REPO

This command will prompt you to select the build report you want to view. These are organized in reverse chronological order by the time of each build:

	Select a build report to view logs:                                                                          	 
                                                                                                                 	 
	Wed, 16 Apr 2025 16:36:52 PDT - Wed, 16 Apr 2025 16:37:08 PDT Success (18-dev, 18.20-dev, 18.20.8-dev)       	 
  > Wed, 16 Apr 2025 16:36:45 PDT - Wed, 16 Apr 2025 16:37:00 PDT Success (20-dev, 20.19-dev, 20.19.0-dev)       	 
	Wed, 16 Apr 2025 16:36:42 PDT - Wed, 16 Apr 2025 16:36:52 PDT Success (18, 18.20, 18.20.8)                   	 
	Wed, 16 Apr 2025 16:36:41 PDT - Wed, 16 Apr 2025 16:36:51 PDT Success (22-slim, 22.14-slim, 22.14.0-slim)    	 
	Wed, 16 Apr 2025 16:36:32 PDT - Wed, 16 Apr 2025 16:36:57 PDT Success (22-dev, 22.14-dev, 22.14.0-dev)       	 
	Wed, 16 Apr 2025 16:36:32 PDT - Wed, 16 Apr 2025 16:36:44 PDT Success (20-slim, 20.19-slim, 20.19.0-slim)    	 
	Wed, 16 Apr 2025 16:36:29 PDT - Wed, 16 Apr 2025 16:36:41 PDT Success (23-slim, 23.11-slim, 23.11.0-slim)    	 
	Wed, 16 Apr 2025 16:36:19 PDT - Wed, 16 Apr 2025 16:36:29 PDT Success (23, 23.11, 23.11.0, latest)           	 
	Wed, 16 Apr 2025 16:36:09 PDT - Wed, 16 Apr 2025 16:36:42 PDT Success (23-dev, 23.11-dev, 23.11.0-dev, latest-dev)
	Wed, 16 Apr 2025 16:36:09 PDT - Wed, 16 Apr 2025 16:36:31 PDT Success (20, 20.19, 20.19.0)                   	 
	Wed, 16 Apr 2025 16:36:09 PDT - Wed, 16 Apr 2025 16:36:31 PDT Success (22, 22.14, 22.14.0)                   	 
	Wed, 16 Apr 2025 16:36:09 PDT - Wed, 16 Apr 2025 16:36:18 PDT Success (18-slim, 18.20-slim, 18.20.8-slim)    	 
	Wed, 16 Apr 2025 16:35:35 PDT - Wed, 16 Apr 2025 16:35:47 PDT Success                                        	 
                                                                                                                 	 
	••••••••••••••                                                                                               	 
                                                                                                                 	 
	↑/k up • ↓/j down • / filter • q quit • ? more  

Highlight your chosen build report and select it by pressing ENTER. This will open up the build’s logs:

2025-04-17T16:00:08-07:00[INFO]Building image with locked configuration: {Contents:{BuildRepositories:[] RuntimeRepositories:[https://apk.cgr.dev/45a0c61eEXAMPLEf050c5fb9ac06a69eed764595]

Learn More

The chainctl commands outlined in this guide show how you can interact with Chainguard’s Custom Assembly tool from the command line.

You can also interact with Custom Assembly with the Chainguard API. Our tutorial on Using the Chainguard API to Manage Custom Assembly Resources outlines how to run a demo application that updates the configuration of a Custom Assembly container through the Chainguard API.