OpenMCF logoOpenMCF

Loading...

GCP Vertex AI Notebook

Deploys a managed Vertex AI Workbench instance (JupyterLab notebook) on a Compute Engine VM with configurable machine type, GPU accelerators, disk encryption, VPC networking, and pre-built or custom container images. Users access notebooks through a secure proxy URL.

What Gets Created

When you deploy a GcpVertexAiNotebook resource, OpenMCF provisions:

  • Workbench Instance — a google_workbench_instance resource configured with the specified machine type, disks, networking, and image
  • Boot Disk (optional configuration) — persistent disk for the OS and JupyterLab runtime, with optional CMEK encryption via a KMS key
  • Data Disk (optional configuration) — persistent disk for user notebooks and datasets, with optional CMEK encryption
  • GPU Accelerator (created only when acceleratorConfig is set) — an NVIDIA GPU attached to the VM for ML training workloads
  • Framework Labels — OpenMCF resource labels applied automatically to the instance for tracking and governance

Prerequisites

  • GCP credentials configured via environment variables or OpenMCF provider config
  • A GCP project with the Notebooks API enabled (notebooks.googleapis.com)
  • A zone in a region that supports Workbench instances (most GCP zones)
  • A VPC network and subnet if deploying with disablePublicIp: true (private networking)
  • A service account if specifying a custom VM identity (recommended for production)
  • A KMS key if using CMEK encryption for boot or data disks — the key must be in the same region as the instance
  • GPU quota in the target zone if using acceleratorConfig

Quick Start

Create a file notebook.yaml:

apiVersion: gcp.openmcf.org/v1
kind: GcpVertexAiNotebook
metadata:
  name: my-notebook
  labels:
    openmcf.org/provisioner: pulumi
    pulumi.openmcf.org/organization: my-org
    pulumi.openmcf.org/project: my-project
    pulumi.openmcf.org/stack.name: dev.GcpVertexAiNotebook.my-notebook
spec:
  projectId:
    value: my-gcp-project
  location: us-central1-a
  machineType: e2-standard-4

Deploy:

openmcf apply -f notebook.yaml

This creates a CPU-only Workbench instance with a default deep learning VM image, 150 GB boot disk, and JupyterLab accessible via the proxy URI in the stack outputs.

Configuration Reference

Required Fields

FieldTypeDescriptionValidation
projectIdStringValueOrRefGCP project where the instance is created. Can reference a GcpProject resource via valueFrom.Required
locationstringGCP zone for the instance (e.g., us-central1-a). Immutable after creation.Required. Pattern: ^[a-z]+-[a-z]+[0-9]-[a-z]$
machineTypestringCompute Engine machine type (e.g., e2-standard-4, n1-standard-8).Required. Min length: 1

Optional Fields

FieldTypeDefaultDescription
instanceNamestringmetadata.nameExplicit GCP instance name. Immutable. Must be a valid RFC1035 hostname.
instanceOwnerslist(string)[]Owner email(s). Currently GCP supports one owner. Sets Single User access mode. Immutable.
desiredStatestringACTIVEInstance state: ACTIVE (running) or STOPPED (suspended, no compute charges).
disableProxyAccessboolfalseIf true, no JupyterLab proxy URL is generated. Immutable.
metadatamap(string){}Custom metadata key-value pairs for the VM.
bootDisk.diskTypestringPD_SSDBoot disk type: PD_STANDARD, PD_SSD, PD_BALANCED, PD_EXTREME.
bootDisk.diskSizeGbint150Boot disk size in GB. Range: 10-64000.
bootDisk.kmsKeyStringValueOrRef—KMS key for CMEK encryption. Can reference GcpKmsKey via valueFrom. Immutable.
dataDisk.diskTypestringPD_STANDARDData disk type: PD_STANDARD, PD_SSD, PD_BALANCED, PD_EXTREME.
dataDisk.diskSizeGbint100Data disk size in GB. Range: 10-64000.
dataDisk.kmsKeyStringValueOrRef—KMS key for CMEK encryption. Can reference GcpKmsKey via valueFrom. Immutable.
acceleratorConfig.typestring—GPU type: NVIDIA_TESLA_T4, NVIDIA_L4, NVIDIA_TESLA_A100, NVIDIA_A100_80GB, etc.
acceleratorConfig.coreCountint—Number of GPU cores (typically 1, 2, 4, or 8).
networkInterface.networkStringValueOrRefdefault VPCVPC network. Can reference GcpVpc via valueFrom. Immutable.
networkInterface.subnetStringValueOrRef—Subnet. Can reference GcpSubnetwork via valueFrom. Immutable.
networkInterface.nicTypestringVIRTIO_NETNIC type: VIRTIO_NET or GVNIC. Immutable.
disablePublicIpboolfalseIf true, no external IP. Instance accessible only via proxy or VPN. Immutable.
enableIpForwardingboolfalseEnable IP forwarding on the VM. Immutable.
serviceAccountStringValueOrRefcompute default SAService account email for VM identity. Can reference GcpServiceAccount via valueFrom. Immutable.
tagslist(string)[]Network tags for firewall rule targeting. Immutable.
vmImage.projectstringdeeplearning-platform-releaseImage project.
vmImage.familystring—Image family (e.g., common-cpu-notebooks, tf-latest-gpu). Mutually exclusive with vmImage.name. Immutable.
vmImage.namestring—Specific image name. Mutually exclusive with vmImage.family. Immutable.
containerImage.repositorystring—Container image repo (e.g., gcr.io/project/image). Required if containerImage is set. Mutually exclusive with vmImage.
containerImage.tagstringlatestContainer image tag.
shieldedInstanceConfig.enableSecureBootboolfalseEnable Secure Boot.
shieldedInstanceConfig.enableVtpmbooltrue (GCP default)Enable Virtual Trusted Platform Module.
shieldedInstanceConfig.enableIntegrityMonitoringbooltrue (GCP default)Enable integrity monitoring.

Examples

Basic CPU Notebook

A minimal notebook for data exploration and light ML work.

apiVersion: gcp.openmcf.org/v1
kind: GcpVertexAiNotebook
metadata:
  name: data-explorer
  labels:
    openmcf.org/provisioner: pulumi
    pulumi.openmcf.org/organization: my-org
    pulumi.openmcf.org/project: my-project
    pulumi.openmcf.org/stack.name: dev.GcpVertexAiNotebook.data-explorer
spec:
  projectId:
    value: my-gcp-project
  location: us-central1-a
  machineType: e2-standard-4
  bootDisk:
    diskType: PD_SSD
    diskSizeGb: 200

GPU Notebook with TensorFlow

A GPU-equipped notebook for training deep learning models.

apiVersion: gcp.openmcf.org/v1
kind: GcpVertexAiNotebook
metadata:
  name: ml-training
  labels:
    openmcf.org/provisioner: pulumi
    pulumi.openmcf.org/organization: my-org
    pulumi.openmcf.org/project: my-project
    pulumi.openmcf.org/stack.name: prod.GcpVertexAiNotebook.ml-training
spec:
  projectId:
    value: my-gcp-project
  location: us-central1-a
  machineType: n1-standard-8
  acceleratorConfig:
    type: NVIDIA_TESLA_T4
    coreCount: 1
  bootDisk:
    diskType: PD_SSD
    diskSizeGb: 200
  dataDisk:
    diskType: PD_SSD
    diskSizeGb: 500
  vmImage:
    project: deeplearning-platform-release
    family: tf-latest-gpu

Private Encrypted Notebook with Foreign Key References

A security-hardened notebook inside a VPC with CMEK encryption, using valueFrom references for infra chart composition.

apiVersion: gcp.openmcf.org/v1
kind: GcpVertexAiNotebook
metadata:
  name: secure-notebook
  labels:
    openmcf.org/provisioner: pulumi
    pulumi.openmcf.org/organization: my-org
    pulumi.openmcf.org/project: my-project
    pulumi.openmcf.org/stack.name: prod.GcpVertexAiNotebook.secure-notebook
spec:
  projectId:
    valueFrom:
      kind: GcpProject
      name: ml-project
  location: us-central1-a
  machineType: e2-standard-4
  disablePublicIp: true
  networkInterface:
    network:
      valueFrom:
        kind: GcpVpc
        name: ml-vpc
    subnet:
      valueFrom:
        kind: GcpSubnetwork
        name: ml-subnet
  serviceAccount:
    valueFrom:
      kind: GcpServiceAccount
      name: notebook-sa
  bootDisk:
    diskType: PD_SSD
    diskSizeGb: 200
    kmsKey:
      valueFrom:
        kind: GcpKmsKey
        name: disk-key
  dataDisk:
    diskType: PD_BALANCED
    diskSizeGb: 500
    kmsKey:
      valueFrom:
        kind: GcpKmsKey
        name: disk-key
  shieldedInstanceConfig:
    enableSecureBoot: true
    enableVtpm: true
    enableIntegrityMonitoring: true
  tags:
    - notebook
    - no-public-ip

Stack Outputs

After deployment, the following outputs are available in status.outputs:

OutputTypeDescription
instance_idstringFully qualified instance ID: projects/{project}/locations/{location}/instances/{id}
instance_namestringShort instance name (matches instanceName or metadata.name)
proxy_uristringJupyterLab proxy URL. Empty if disableProxyAccess is true.
statestringCurrent instance state: ACTIVE, STOPPED, INITIALIZING, STARTING, STOPPING, etc.
creatorstringEmail address of the entity that created the instance
create_timestringRFC3339 timestamp of instance creation

Related Components

  • GcpProject — project where the notebook is created
  • GcpVpc — VPC network for private notebook deployments
  • GcpSubnetwork — subnet for VPC-connected notebooks
  • GcpServiceAccount — VM identity for accessing GCP resources
  • GcpKmsKey — encryption key for CMEK-encrypted disks

Next article

GCP VPC

GCP VPC Deploys a GCP VPC network in custom subnet mode by default, with configurable dynamic routing and optional Private Services Access for Google managed services like Cloud SQL and Memorystore. The component automatically enables the Compute Engine API on the target project before creating the network. What Gets Created When you deploy a GcpVpc resource, OpenMCF provisions: Compute Engine API enablement — a googleprojectservice resource that activates compute.googleapis.com on the target...
Read next article