Configure AWS SageMaker App Image Configs

The aws:sagemaker/appImageConfig:AppImageConfig resource, part of the Pulumi AWS provider, defines configuration for custom container images used in SageMaker Studio applications. This guide focuses on three capabilities: Kernel Gateway mode for notebook kernels, Code Editor mode for VS Code-like environments, and file system configuration.

Image configs reference container images stored in ECR and are attached to SageMaker Studio domains or user profiles. Each config must specify exactly one application mode: Kernel Gateway, Code Editor, or JupyterLab. The examples are intentionally small. Combine them with your own ECR images and Studio infrastructure.

Configure a Kernel Gateway image with kernel specs

SageMaker Studio notebooks require image configurations that define which kernels are available and how they’re invoked.

import * as pulumi from "@pulumi/pulumi";
import * as aws from "@pulumi/aws";

const test = new aws.sagemaker.AppImageConfig("test", {
    appImageConfigName: "example",
    kernelGatewayImageConfig: {
        kernelSpecs: [{
            name: "example",
        }],
    },
});

import pulumi
import pulumi_aws as aws

test = aws.sagemaker.AppImageConfig("test",
    app_image_config_name="example",
    kernel_gateway_image_config={
        "kernel_specs": [{
            "name": "example",
        }],
    })

package main

import (
	"github.com/pulumi/pulumi-aws/sdk/v7/go/aws/sagemaker"
	"github.com/pulumi/pulumi/sdk/v3/go/pulumi"
)

func main() {
	pulumi.Run(func(ctx *pulumi.Context) error {
		_, err := sagemaker.NewAppImageConfig(ctx, "test", &sagemaker.AppImageConfigArgs{
			AppImageConfigName: pulumi.String("example"),
			KernelGatewayImageConfig: &sagemaker.AppImageConfigKernelGatewayImageConfigArgs{
				KernelSpecs: sagemaker.AppImageConfigKernelGatewayImageConfigKernelSpecArray{
					&sagemaker.AppImageConfigKernelGatewayImageConfigKernelSpecArgs{
						Name: pulumi.String("example"),
					},
				},
			},
		})
		if err != nil {
			return err
		}
		return nil
	})
}

using System.Collections.Generic;
using System.Linq;
using Pulumi;
using Aws = Pulumi.Aws;

return await Deployment.RunAsync(() => 
{
    var test = new Aws.Sagemaker.AppImageConfig("test", new()
    {
        AppImageConfigName = "example",
        KernelGatewayImageConfig = new Aws.Sagemaker.Inputs.AppImageConfigKernelGatewayImageConfigArgs
        {
            KernelSpecs = new[]
            {
                new Aws.Sagemaker.Inputs.AppImageConfigKernelGatewayImageConfigKernelSpecArgs
                {
                    Name = "example",
                },
            },
        },
    });

});

package generated_program;

import com.pulumi.Context;
import com.pulumi.Pulumi;
import com.pulumi.core.Output;
import com.pulumi.aws.sagemaker.AppImageConfig;
import com.pulumi.aws.sagemaker.AppImageConfigArgs;
import com.pulumi.aws.sagemaker.inputs.AppImageConfigKernelGatewayImageConfigArgs;
import java.util.List;
import java.util.ArrayList;
import java.util.Map;
import java.io.File;
import java.nio.file.Files;
import java.nio.file.Paths;

public class App {
    public static void main(String[] args) {
        Pulumi.run(App::stack);
    }

    public static void stack(Context ctx) {
        var test = new AppImageConfig("test", AppImageConfigArgs.builder()
            .appImageConfigName("example")
            .kernelGatewayImageConfig(AppImageConfigKernelGatewayImageConfigArgs.builder()
                .kernelSpecs(AppImageConfigKernelGatewayImageConfigKernelSpecArgs.builder()
                    .name("example")
                    .build())
                .build())
            .build());

    }
}

resources:
  test:
    type: aws:sagemaker:AppImageConfig
    properties:
      appImageConfigName: example
      kernelGatewayImageConfig:
        kernelSpecs:
          - name: example

The kernelGatewayImageConfig property enables Kernel Gateway mode, which runs Jupyter kernels in your custom container. The kernelSpecs array defines available kernels; each kernel needs a name that matches the kernel specification in your container image. SageMaker uses this configuration when users select your custom image in Studio notebooks.

Enable Code Editor mode with default settings

SageMaker Studio supports Code Editor applications that require their own configuration type.

import * as pulumi from "@pulumi/pulumi";
import * as aws from "@pulumi/aws";

const test = new aws.sagemaker.AppImageConfig("test", {
    appImageConfigName: "example",
    codeEditorAppImageConfig: {},
});

import pulumi
import pulumi_aws as aws

test = aws.sagemaker.AppImageConfig("test",
    app_image_config_name="example",
    code_editor_app_image_config={})

package main

import (
	"github.com/pulumi/pulumi-aws/sdk/v7/go/aws/sagemaker"
	"github.com/pulumi/pulumi/sdk/v3/go/pulumi"
)

func main() {
	pulumi.Run(func(ctx *pulumi.Context) error {
		_, err := sagemaker.NewAppImageConfig(ctx, "test", &sagemaker.AppImageConfigArgs{
			AppImageConfigName:       pulumi.String("example"),
			CodeEditorAppImageConfig: &sagemaker.AppImageConfigCodeEditorAppImageConfigArgs{},
		})
		if err != nil {
			return err
		}
		return nil
	})
}

using System.Collections.Generic;
using System.Linq;
using Pulumi;
using Aws = Pulumi.Aws;

return await Deployment.RunAsync(() => 
{
    var test = new Aws.Sagemaker.AppImageConfig("test", new()
    {
        AppImageConfigName = "example",
        CodeEditorAppImageConfig = null,
    });

});

package generated_program;

import com.pulumi.Context;
import com.pulumi.Pulumi;
import com.pulumi.core.Output;
import com.pulumi.aws.sagemaker.AppImageConfig;
import com.pulumi.aws.sagemaker.AppImageConfigArgs;
import com.pulumi.aws.sagemaker.inputs.AppImageConfigCodeEditorAppImageConfigArgs;
import java.util.List;
import java.util.ArrayList;
import java.util.Map;
import java.io.File;
import java.nio.file.Files;
import java.nio.file.Paths;

public class App {
    public static void main(String[] args) {
        Pulumi.run(App::stack);
    }

    public static void stack(Context ctx) {
        var test = new AppImageConfig("test", AppImageConfigArgs.builder()
            .appImageConfigName("example")
            .codeEditorAppImageConfig(AppImageConfigCodeEditorAppImageConfigArgs.builder()
                .build())
            .build());

    }
}

resources:
  test:
    type: aws:sagemaker:AppImageConfig
    properties:
      appImageConfigName: example
      codeEditorAppImageConfig: {}

The codeEditorAppImageConfig property enables Code Editor mode for VS Code-like environments. Empty configuration blocks are valid and apply SageMaker defaults for container startup and resource allocation. You must specify exactly one of codeEditorAppImageConfig, jupyterLabImageConfig, or kernelGatewayImageConfig per image config.

Add file system configuration to Kernel Gateway

Kernel Gateway images can include file system settings that control container storage access.

import * as pulumi from "@pulumi/pulumi";
import * as aws from "@pulumi/aws";

const test = new aws.sagemaker.AppImageConfig("test", {
    appImageConfigName: "example",
    kernelGatewayImageConfig: {
        kernelSpecs: [{
            name: "example",
        }],
        fileSystemConfig: {},
    },
});

import pulumi
import pulumi_aws as aws

test = aws.sagemaker.AppImageConfig("test",
    app_image_config_name="example",
    kernel_gateway_image_config={
        "kernel_specs": [{
            "name": "example",
        }],
        "file_system_config": {},
    })

package main

import (
	"github.com/pulumi/pulumi-aws/sdk/v7/go/aws/sagemaker"
	"github.com/pulumi/pulumi/sdk/v3/go/pulumi"
)

func main() {
	pulumi.Run(func(ctx *pulumi.Context) error {
		_, err := sagemaker.NewAppImageConfig(ctx, "test", &sagemaker.AppImageConfigArgs{
			AppImageConfigName: pulumi.String("example"),
			KernelGatewayImageConfig: &sagemaker.AppImageConfigKernelGatewayImageConfigArgs{
				KernelSpecs: sagemaker.AppImageConfigKernelGatewayImageConfigKernelSpecArray{
					&sagemaker.AppImageConfigKernelGatewayImageConfigKernelSpecArgs{
						Name: pulumi.String("example"),
					},
				},
				FileSystemConfig: &sagemaker.AppImageConfigKernelGatewayImageConfigFileSystemConfigArgs{},
			},
		})
		if err != nil {
			return err
		}
		return nil
	})
}

using System.Collections.Generic;
using System.Linq;
using Pulumi;
using Aws = Pulumi.Aws;

return await Deployment.RunAsync(() => 
{
    var test = new Aws.Sagemaker.AppImageConfig("test", new()
    {
        AppImageConfigName = "example",
        KernelGatewayImageConfig = new Aws.Sagemaker.Inputs.AppImageConfigKernelGatewayImageConfigArgs
        {
            KernelSpecs = new[]
            {
                new Aws.Sagemaker.Inputs.AppImageConfigKernelGatewayImageConfigKernelSpecArgs
                {
                    Name = "example",
                },
            },
            FileSystemConfig = null,
        },
    });

});

package generated_program;

import com.pulumi.Context;
import com.pulumi.Pulumi;
import com.pulumi.core.Output;
import com.pulumi.aws.sagemaker.AppImageConfig;
import com.pulumi.aws.sagemaker.AppImageConfigArgs;
import com.pulumi.aws.sagemaker.inputs.AppImageConfigKernelGatewayImageConfigArgs;
import com.pulumi.aws.sagemaker.inputs.AppImageConfigKernelGatewayImageConfigFileSystemConfigArgs;
import java.util.List;
import java.util.ArrayList;
import java.util.Map;
import java.io.File;
import java.nio.file.Files;
import java.nio.file.Paths;

public class App {
    public static void main(String[] args) {
        Pulumi.run(App::stack);
    }

    public static void stack(Context ctx) {
        var test = new AppImageConfig("test", AppImageConfigArgs.builder()
            .appImageConfigName("example")
            .kernelGatewayImageConfig(AppImageConfigKernelGatewayImageConfigArgs.builder()
                .kernelSpecs(AppImageConfigKernelGatewayImageConfigKernelSpecArgs.builder()
                    .name("example")
                    .build())
                .fileSystemConfig(AppImageConfigKernelGatewayImageConfigFileSystemConfigArgs.builder()
                    .build())
                .build())
            .build());

    }
}

resources:
  test:
    type: aws:sagemaker:AppImageConfig
    properties:
      appImageConfigName: example
      kernelGatewayImageConfig:
        kernelSpecs:
          - name: example
        fileSystemConfig: {}

The fileSystemConfig property within kernelGatewayImageConfig controls how the container accesses file systems. Empty blocks apply SageMaker defaults for mount paths and permissions. This extends the basic Kernel Gateway configuration with storage behavior controls.

Beyond these examples

These snippets focus on specific image config features: Kernel Gateway and Code Editor modes, kernel specifications, and file system configuration. They’re intentionally minimal rather than full Studio deployments.

The examples assume pre-existing infrastructure such as SageMaker Studio domains or user profiles, and container images in ECR. They focus on configuring the image rather than provisioning the surrounding Studio environment.

To keep things focused, common image config patterns are omitted, including:

JupyterLab image configuration (jupyterLabImageConfig)
Resource tagging (tags)
Detailed kernel spec properties (displayName, arguments)
File system mount paths and permissions

These omissions are intentional: the goal is to illustrate how each image config mode is wired, not provide drop-in Studio modules. See the SageMaker AppImageConfig resource reference for all available configuration options.

Let's configure AWS SageMaker App Image Configs

Get started with Pulumi Cloud, then follow our quick setup guide to deploy this infrastructure.

Try Pulumi Cloud for FREE

Frequently Asked Questions

Configuration Requirements

Which image config type should I use?

Choose based on your application: codeEditorAppImageConfig for Code Editor apps, jupyterLabImageConfig for JupyterLab apps, or kernelGatewayImageConfig for KernelGateway apps. You must configure exactly one of these three types.

Can I use an empty configuration block?

Yes, empty blocks like codeEditorAppImageConfig: {} are valid configurations, as shown in the Code Editor example.

Immutability & Limitations

Can I change the App Image Config name after creation?

No, appImageConfigName is immutable and cannot be changed after creation. Changing it requires replacing the resource.

Can I configure multiple image config types?

No, you must configure exactly one of codeEditorAppImageConfig, jupyterLabImageConfig, or kernelGatewayImageConfig. Configuring multiple or none will cause errors.

Using a different cloud?

Explore analytics guides for other cloud providers:

Azure Guides GCP Guides