Merge pull request #427 from crazy-max/keep-state

Keep BuildKit state support

.github/workflows/ci.yml

@@ -603,3 +603,44 @@ jobs:
             exit 1
           fi
         shell: bash
+
+  keep-state:
+    runs-on: ubuntu-latest
+    steps:
+      -
+        name: Checkout
+        uses: actions/checkout@v4
+      -
+        name: Set up Docker Buildx
+        uses: ./
+        with:
+          name: foo
+          keep-state: true
+      -
+        name: Set up Docker Buildx
+        uses: ./
+        with:
+          name: foo
+
+  keep-state-error:
+    runs-on: ubuntu-latest
+    steps:
+      -
+        name: Checkout
+        uses: actions/checkout@v4
+      -
+        name: Set up Docker Buildx
+        id: buildx
+        continue-on-error: true
+        uses: ./
+        with:
+          driver: docker
+          keep-state: true
+      -
+        name: Check
+        run: |
+          echo "${{ toJson(steps.buildx) }}"
+          if [ "${{ steps.buildx.outcome }}" != "failure" ] || [ "${{ steps.buildx.conclusion }}" != "success" ]; then
+            echo "::error::Should have failed"
+            exit 1
+          fi

README.md

@@ -85,21 +85,23 @@ The following inputs can be used as `step.with` keys:
 > platforms: linux/amd64,linux/arm64
 > ```
 
-| Name                         | Type     | Default            | Description                                                                                                                                                                  |
+| Name                         | Type     | Default            | Description                                                                                                                                                                 |
-|------------------------------|----------|--------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+|------------------------------|----------|--------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `version`                    | String   |                    | [Buildx](https://github.com/docker/buildx) version. (eg. `v0.3.0`, `latest`, `https://github.com/docker/buildx.git#master`)                                                  |
+| `version`                    | String   |                    | [Buildx](https://github.com/docker/buildx) version. (eg. `v0.3.0`, `latest`, `https://github.com/docker/buildx.git#master`)                                                 |
-| `driver`                     | String   | `docker-container` | Sets the [builder driver](https://docs.docker.com/engine/reference/commandline/buildx_create/#driver) to be used                                                             |
+| `name`                       | String   |                    | Name of the builder. If not specified, one will be generated or if it already exists, it will be used instead of creating a new one                                         |
-| `driver-opts`                | List     |                    | List of additional [driver-specific options](https://docs.docker.com/engine/reference/commandline/buildx_create/#driver-opt) (eg. `image=moby/buildkit:master`)              |
+| `driver`                     | String   | `docker-container` | Sets the [builder driver](https://docs.docker.com/engine/reference/commandline/buildx_create/#driver) to be used                                                            |
-| `buildkitd-flags`            | String   |                    | [BuildKit daemon flags](https://docs.docker.com/engine/reference/commandline/buildx_create/#buildkitd-flags)                                                                 |
+| `driver-opts`                | List     |                    | List of additional [driver-specific options](https://docs.docker.com/engine/reference/commandline/buildx_create/#driver-opt) (eg. `image=moby/buildkit:master`)             |
-| `buildkitd-config` \*        | String   |                    | [BuildKit daemon config file](https://docs.docker.com/engine/reference/commandline/buildx_create/#config)                                                                    |
+| `buildkitd-flags`            | String   |                    | [BuildKit daemon flags](https://docs.docker.com/engine/reference/commandline/buildx_create/#buildkitd-flags)                                                                |
-| `buildkitd-config-inline` \* | String   |                    | Same as `buildkitd-config` but inline                                                                                                                                        |
+| `buildkitd-config` \*        | String   |                    | [BuildKit daemon config file](https://docs.docker.com/engine/reference/commandline/buildx_create/#config)                                                                   |
-| `install`                    | Bool     | `false`            | Sets up `docker build` command as an alias to `docker buildx`                                                                                                                |
+| `buildkitd-config-inline` \* | String   |                    | Same as `buildkitd-config` but inline                                                                                                                                       |
-| `use`                        | Bool     | `true`             | Switch to this builder instance                                                                                                                                              |
+| `install`                    | Bool     | `false`            | Sets up `docker build` command as an alias to `docker buildx`                                                                                                               |
-| `endpoint`                   | String   |                    | [Optional address for docker socket](https://docs.docker.com/engine/reference/commandline/buildx_create/#description) or context from `docker context ls`                    |
+| `use`                        | Bool     | `true`             | Switch to this builder instance                                                                                                                                             |
-| `platforms`                  | List/CSV |                    | Fixed [platforms](https://docs.docker.com/engine/reference/commandline/buildx_create/#platform) for current node. If not empty, values take priority over the detected ones. |
+| `endpoint`                   | String   |                    | [Optional address for docker socket](https://docs.docker.com/engine/reference/commandline/buildx_create/#description) or context from `docker context ls`                   |
-| `append`                     | YAML     |                    | [Append additional nodes](https://docs.docker.com/build/ci/github-actions/configure-builder/#append-additional-nodes-to-the-builder) to the builder                          |
+| `platforms`                  | List/CSV |                    | Fixed [platforms](https://docs.docker.com/engine/reference/commandline/buildx_create/#platform) for current node. If not empty, values take priority over the detected ones |
-| `cache-binary`               | Bool     | `true`             | Cache buildx binary to GitHub Actions cache backend                                                                                                                          |
+| `append`                     | YAML     |                    | [Append additional nodes](https://docs.docker.com/build/ci/github-actions/configure-builder/#append-additional-nodes-to-the-builder) to the builder                         |
-| `cleanup`                    | Bool     | `true`             | Cleanup temp files and remove builder at the end of a job                                                                                                                    |
+| `keep-state`                 | Bool     | `false`            | Keep BuildKit state on `cleanup`. This is only useful on persistent self-hosted runners                                                                                     |
+| `cache-binary`               | Bool     | `true`             | Cache buildx binary to GitHub Actions cache backend                                                                                                                         |
+| `cleanup`                    | Bool     | `true`             | Cleanup temp files and remove builder at the end of a job                                                                                                                   |
 
 > [!IMPORTANT]
 > If you set the `buildkitd-flags` input, the default flags (`--allow-insecure-entitlement security.insecure --allow-insecure-entitlement network.host`)

__tests__/context.test.ts

@@ -56,6 +56,7 @@ describe('getCreateArgs', () => {
         ['use', 'true'],
         ['cache-binary', 'true'],
         ['cleanup', 'true'],
+        ['keep-state', 'false']
       ]),
       [
         'create',
@@ -74,6 +75,7 @@ describe('getCreateArgs', () => {
         ['use', 'true'],
         ['cache-binary', 'true'],
         ['cleanup', 'true'],
+        ['keep-state', 'false']
       ]),
       [
         'create',
@@ -92,6 +94,7 @@ describe('getCreateArgs', () => {
         ['driver-opts', 'image=moby/buildkit:master\nnetwork=host'],
         ['cache-binary', 'true'],
         ['cleanup', 'true'],
+        ['keep-state', 'false']
       ]),
       [
         'create',
@@ -112,6 +115,7 @@ describe('getCreateArgs', () => {
         ['use', 'true'],
         ['cache-binary', 'true'],
         ['cleanup', 'true'],
+        ['keep-state', 'false']
       ]),
       [
         'create',
@@ -132,6 +136,7 @@ describe('getCreateArgs', () => {
         ['use', 'true'],
         ['cache-binary', 'true'],
         ['cleanup', 'true'],
+        ['keep-state', 'false']
       ]),
       [
         'create',
@@ -151,6 +156,7 @@ describe('getCreateArgs', () => {
         ['driver-opts', `"env.no_proxy=localhost,127.0.0.1,.mydomain"`],
         ['cache-binary', 'true'],
         ['cleanup', 'true'],
+        ['keep-state', 'false'],
       ]),
       [
         'create',
@@ -169,6 +175,7 @@ describe('getCreateArgs', () => {
         ['platforms', 'linux/amd64\n"linux/arm64,linux/arm/v7"'],
         ['cache-binary', 'true'],
         ['cleanup', 'true'],
+        ['keep-state', 'false'],
       ]),
       [
         'create',
@@ -187,6 +194,7 @@ describe('getCreateArgs', () => {
         ['driver', 'unknown'],
         ['cache-binary', 'true'],
         ['cleanup', 'true'],
+        ['keep-state', 'false'],
       ]),
       [
         'create',
@@ -203,6 +211,7 @@ describe('getCreateArgs', () => {
         ['buildkitd-config', path.join(fixturesDir, 'buildkitd.toml')],
         ['cache-binary', 'true'],
         ['cleanup', 'true'],
+        ['keep-state', 'false'],
       ]),
       [
         'create',
@@ -221,6 +230,7 @@ describe('getCreateArgs', () => {
         ['buildkitd-config-inline', 'debug = true'],
         ['cache-binary', 'true'],
         ['cleanup', 'true'],
+        ['keep-state', 'false'],
       ]),
       [
         'create',
@@ -240,6 +250,7 @@ describe('getCreateArgs', () => {
         ['buildkitd-flags', '--allow-insecure-entitlement network.host'],
         ['cache-binary', 'true'],
         ['cleanup', 'true'],
+        ['keep-state', 'false'],
       ]),
       [
         'create',
@@ -247,7 +258,45 @@ describe('getCreateArgs', () => {
         '--driver', 'cloud',
         '--buildkitd-flags', '--allow-insecure-entitlement network.host',
       ]
-    ]
+    ],
+    [
+      11,
+      'v0.10.3',
+      new Map<string, string>([
+        ['install', 'false'],
+        ['use', 'true'],
+        ['cleanup', 'true'],
+        ['cache-binary', 'true'],
+        ['keep-state', 'false'],
+        ['name', 'test-builder-name'],
+      ]),
+      [
+        'create',
+        '--name', 'test-builder-name',
+        '--driver', 'docker-container',
+        '--buildkitd-flags', '--allow-insecure-entitlement security.insecure --allow-insecure-entitlement network.host',
+        '--use'
+      ]
+    ],
+    [
+      12,
+      'v0.10.3',
+      new Map<string, string>([
+        ['install', 'false'],
+        ['use', 'true'],
+        ['cleanup', 'true'],
+        ['cache-binary', 'true'],
+        ['keep-state', 'true'],
+        ['name', 'test-builder-name'],
+      ]),
+      [
+        'create',
+        '--name', 'test-builder-name',
+        '--driver', 'docker-container',
+        '--buildkitd-flags', '--allow-insecure-entitlement security.insecure --allow-insecure-entitlement network.host',
+        '--use',
+      ]
+    ],
   ])(
     '[%d] given buildx %s and %p as inputs, returns %p',
     async (num: number, buildxVersion: string, inputs: Map<string, string>, expected: Array<string>) => {
@@ -285,6 +334,7 @@ describe('getAppendArgs', () => {
         ['use', 'true'],
         ['cache-binary', 'true'],
         ['cleanup', 'true'],
+        ['keep-state', 'false']
       ]),
       {
         "name": "aws_graviton2",
@@ -343,6 +393,7 @@ describe('getVersion', () => {
         ['use', 'true'],
         ['cache-binary', 'true'],
         ['cleanup', 'true'],
+        ['keep-state', 'false']
       ]),
       ''
     ],
@@ -354,7 +405,8 @@ describe('getVersion', () => {
         ['install', 'false'],
         ['use', 'true'],
         ['cache-binary', 'true'],
-        ['cleanup', 'true']
+        ['cleanup', 'true'],
+        ['keep-state', 'false']
       ]),
       'latest'
     ],
@@ -366,7 +418,8 @@ describe('getVersion', () => {
         ['install', 'false'],
         ['use', 'true'],
         ['cache-binary', 'true'],
-        ['cleanup', 'true']
+        ['cleanup', 'true'],
+        ['keep-state', 'false']
       ]),
       'edge'
     ],
@@ -378,7 +431,8 @@ describe('getVersion', () => {
         ['install', 'false'],
         ['use', 'true'],
         ['cache-binary', 'true'],
-        ['cleanup', 'true']
+        ['cleanup', 'true'],
+        ['keep-state', 'false']
       ]),
       'v0.19.2'
     ],
@@ -391,7 +445,8 @@ describe('getVersion', () => {
         ['install', 'false'],
         ['use', 'true'],
         ['cache-binary', 'true'],
-        ['cleanup', 'true']
+        ['cleanup', 'true'],
+        ['keep-state', 'false']
       ]),
       'cloud:latest'
     ],
@@ -404,7 +459,8 @@ describe('getVersion', () => {
         ['install', 'false'],
         ['use', 'true'],
         ['cache-binary', 'true'],
-        ['cleanup', 'true']
+        ['cleanup', 'true'],
+        ['keep-state', 'false']
       ]),
       'cloud:edge'
     ],
@@ -417,6 +473,7 @@ describe('getVersion', () => {
         ['use', 'true'],
         ['cache-binary', 'true'],
         ['cleanup', 'true'],
+        ['keep-state', 'false']
       ]),
       'cloud:latest'
     ],
@@ -430,6 +487,7 @@ describe('getVersion', () => {
         ['use', 'true'],
         ['cache-binary', 'true'],
         ['cleanup', 'true'],
+        ['keep-state', 'false']
       ]),
       'cloud:v0.11.2-desktop.2'
     ],
@@ -442,6 +500,7 @@ describe('getVersion', () => {
         ['use', 'true'],
         ['cache-binary', 'true'],
         ['cleanup', 'true'],
+        ['keep-state', 'false']
       ]),
       'cloud:v0.11.2-desktop.2'
     ],

action.yml

@@ -34,6 +34,9 @@ inputs:
     description: 'Switch to this builder instance'
     default: 'true'
     required: false
+  name:
+    description: 'Name of the builder. If not specified, one will be generated or if it already exists, it will be used instead of creating a new one.'
+    required: false
   endpoint:
     description: 'Optional address for docker socket or context from `docker context ls`'
     required: false
@@ -43,6 +46,10 @@ inputs:
   append:
     description: 'Append additional nodes to the builder'
     required: false
+  keep-state:
+    description: 'Keep BuildKit state on cleanup. This is only useful on persistent self-hosted runners.'
+    default: 'false'
+    required: false
   cache-binary:
     description: 'Cache buildx binary to GitHub Actions cache backend'
     default: 'true'

src/context.ts

@@ -25,12 +25,13 @@ export interface Inputs {
   append: string;
   cacheBinary: boolean;
   cleanup: boolean;
+  keepState: boolean;
 }
 
 export async function getInputs(): Promise<Inputs> {
   return {
     version: core.getInput('version'),
-    name: await getBuilderName(core.getInput('driver') || 'docker-container'),
+    name: await getBuilderName(core.getInput('name'), core.getInput('driver') || 'docker-container'),
     driver: core.getInput('driver') || 'docker-container',
     driverOpts: Util.getInputList('driver-opts', {ignoreComma: true, quote: false}),
     buildkitdFlags: core.getInput('buildkitd-flags'),
@@ -41,13 +42,14 @@ export async function getInputs(): Promise<Inputs> {
     buildkitdConfig: core.getInput('buildkitd-config') || core.getInput('config'),
     buildkitdConfigInline: core.getInput('buildkitd-config-inline') || core.getInput('config-inline'),
     append: core.getInput('append'),
+    keepState: core.getBooleanInput('keep-state'),
     cacheBinary: core.getBooleanInput('cache-binary'),
     cleanup: core.getBooleanInput('cleanup')
   };
 }
 
-export async function getBuilderName(driver: string): Promise<string> {
+export async function getBuilderName(name: string, driver: string): Promise<string> {
-  return driver == 'docker' ? await Docker.context() : `builder-${crypto.randomUUID()}`;
+  return driver == 'docker' ? await Docker.context() : name || `builder-${crypto.randomUUID()}`;
 }
 
 export async function getCreateArgs(inputs: Inputs, toolkit: Toolkit): Promise<Array<string>> {

src/main.ts

@@ -28,6 +28,12 @@ actionsToolkit.run(
     const standalone = await toolkit.buildx.isStandalone();
     stateHelper.setStandalone(standalone);
 
+    if (inputs.keepState && inputs.driver !== 'docker-container') {
+      // https://docs.docker.com/reference/cli/docker/buildx/rm/#keep-state
+      throw new Error(`Cannot use keep-state with ${inputs.driver} driver`);
+    }
+    stateHelper.setKeepState(inputs.keepState);
+
     await core.group(`Docker info`, async () => {
       try {
         await Docker.printVersion();
@@ -118,22 +124,26 @@ actionsToolkit.run(
 
     if (inputs.driver !== 'docker') {
       await core.group(`Creating a new builder instance`, async () => {
-        const certsDriverOpts = Buildx.resolveCertsDriverOpts(inputs.driver, inputs.endpoint, {
+        if (await toolkit.builder.exists(inputs.name)) {
-          cacert: process.env[`${context.builderNodeEnvPrefix}_0_AUTH_TLS_CACERT`],
+          core.info(`Builder ${inputs.name} already exists, skipping creation`);
-          cert: process.env[`${context.builderNodeEnvPrefix}_0_AUTH_TLS_CERT`],
+        } else {
-          key: process.env[`${context.builderNodeEnvPrefix}_0_AUTH_TLS_KEY`]
+          const certsDriverOpts = Buildx.resolveCertsDriverOpts(inputs.driver, inputs.endpoint, {
-        });
+            cacert: process.env[`${context.builderNodeEnvPrefix}_0_AUTH_TLS_CACERT`],
-        if (certsDriverOpts.length > 0) {
+            cert: process.env[`${context.builderNodeEnvPrefix}_0_AUTH_TLS_CERT`],
-          inputs.driverOpts = [...inputs.driverOpts, ...certsDriverOpts];
+            key: process.env[`${context.builderNodeEnvPrefix}_0_AUTH_TLS_KEY`]
-        }
+          });
-        const createCmd = await toolkit.buildx.getCommand(await context.getCreateArgs(inputs, toolkit));
+          if (certsDriverOpts.length > 0) {
-        await Exec.getExecOutput(createCmd.command, createCmd.args, {
+            inputs.driverOpts = [...inputs.driverOpts, ...certsDriverOpts];
-          ignoreReturnCode: true
-        }).then(res => {
-          if (res.stderr.length > 0 && res.exitCode != 0) {
-            throw new Error(res.stderr.match(/(.*)\s*$/)?.[0]?.trim() ?? 'unknown error');
           }
-        });
+          const createCmd = await toolkit.buildx.getCommand(await context.getCreateArgs(inputs, toolkit));
+          await Exec.getExecOutput(createCmd.command, createCmd.args, {
+            ignoreReturnCode: true
+          }).then(res => {
+            if (res.stderr.length > 0 && res.exitCode != 0) {
+              throw new Error(res.stderr.match(/(.*)\s*$/)?.[0]?.trim() ?? 'unknown error');
+            }
+          });
+        }
       });
     }
 
@@ -249,7 +259,7 @@ actionsToolkit.run(
         const buildx = new Buildx({standalone: stateHelper.standalone});
         const builder = new Builder({buildx: buildx});
         if (await builder.exists(stateHelper.builderName)) {
-          const rmCmd = await buildx.getCommand(['rm', stateHelper.builderName]);
+          const rmCmd = await buildx.getCommand(['rm', stateHelper.builderName, ...(stateHelper.keepState ? ['--keep-state'] : [])]);
           await Exec.getExecOutput(rmCmd.command, rmCmd.args, {
             ignoreReturnCode: true
           }).then(res => {

src/state-helper.ts

@@ -9,6 +9,7 @@ export const certsDir = process.env['STATE_certsDir'] || '';
 export const tmpDockerContext = process.env['STATE_tmpDockerContext'] || '';
 export const cleanup = /true/i.test(process.env['STATE_cleanup'] || '');
 export const buildxIsDefaultBuilder = /true/i.test(process.env['STATE_buildxIsDefaultBuilder'] || '');
+export const keepState = !!process.env['STATE_keepState'];
 
 export function setDebug(debug: string) {
   core.saveState('isDebug', debug);
@@ -45,3 +46,7 @@ export function setCleanup(cleanup: boolean) {
 export function setBuildxIsDefaultBuilder(buildxIsDefaultBuilder: boolean) {
   core.saveState('buildxIsDefaultBuilder', buildxIsDefaultBuilder);
 }
+
+export function setKeepState(retain: boolean) {
+  core.saveState('keepState', retain);
+}