Class InstanceTemplate


  • public class InstanceTemplate
    extends com.pulumi.resources.CustomResource
    Manages a VM instance template resource within GCE. For more information see [the official documentation](https://cloud.google.com/compute/docs/instance-templates) and [API](https://cloud.google.com/compute/docs/reference/latest/instanceTemplates). ## Example Usage ```java package generated_program; import com.pulumi.Context; import com.pulumi.Pulumi; import com.pulumi.core.Output; import com.pulumi.gcp.serviceAccount.Account; import com.pulumi.gcp.serviceAccount.AccountArgs; import com.pulumi.gcp.compute.ComputeFunctions; import com.pulumi.gcp.compute.inputs.GetImageArgs; import com.pulumi.gcp.compute.Disk; import com.pulumi.gcp.compute.DiskArgs; import com.pulumi.gcp.compute.ResourcePolicy; import com.pulumi.gcp.compute.ResourcePolicyArgs; import com.pulumi.gcp.compute.inputs.ResourcePolicySnapshotSchedulePolicyArgs; import com.pulumi.gcp.compute.inputs.ResourcePolicySnapshotSchedulePolicyScheduleArgs; import com.pulumi.gcp.compute.inputs.ResourcePolicySnapshotSchedulePolicyScheduleDailyScheduleArgs; import com.pulumi.gcp.compute.InstanceTemplate; import com.pulumi.gcp.compute.InstanceTemplateArgs; import com.pulumi.gcp.compute.inputs.InstanceTemplateSchedulingArgs; import com.pulumi.gcp.compute.inputs.InstanceTemplateDiskArgs; import com.pulumi.gcp.compute.inputs.InstanceTemplateNetworkInterfaceArgs; import com.pulumi.gcp.compute.inputs.InstanceTemplateServiceAccountArgs; 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 defaultAccount = new Account("defaultAccount", AccountArgs.builder() .accountId("service-account-id") .displayName("Service Account") .build()); final var myImage = ComputeFunctions.getImage(GetImageArgs.builder() .family("debian-11") .project("debian-cloud") .build()); var foobar = new Disk("foobar", DiskArgs.builder() .image(myImage.applyValue(getImageResult -> getImageResult.selfLink())) .size(10) .type("pd-ssd") .zone("us-central1-a") .build()); var dailyBackup = new ResourcePolicy("dailyBackup", ResourcePolicyArgs.builder() .region("us-central1") .snapshotSchedulePolicy(ResourcePolicySnapshotSchedulePolicyArgs.builder() .schedule(ResourcePolicySnapshotSchedulePolicyScheduleArgs.builder() .dailySchedule(ResourcePolicySnapshotSchedulePolicyScheduleDailyScheduleArgs.builder() .daysInCycle(1) .startTime("04:00") .build()) .build()) .build()) .build()); var defaultInstanceTemplate = new InstanceTemplate("defaultInstanceTemplate", InstanceTemplateArgs.builder() .description("This template is used to create app server instances.") .tags( "foo", "bar") .labels(Map.of("environment", "dev")) .instanceDescription("description assigned to instances") .machineType("e2-medium") .canIpForward(false) .scheduling(InstanceTemplateSchedulingArgs.builder() .automaticRestart(true) .onHostMaintenance("MIGRATE") .build()) .disks( InstanceTemplateDiskArgs.builder() .sourceImage("debian-cloud/debian-11") .autoDelete(true) .boot(true) .resourcePolicies(dailyBackup.id()) .build(), InstanceTemplateDiskArgs.builder() .source(foobar.name()) .autoDelete(false) .boot(false) .build()) .networkInterfaces(InstanceTemplateNetworkInterfaceArgs.builder() .network("default") .build()) .metadata(Map.of("foo", "bar")) .serviceAccount(InstanceTemplateServiceAccountArgs.builder() .email(defaultAccount.email()) .scopes("cloud-platform") .build()) .build()); } } ``` ### Automatic Envoy Deployment ```java package generated_program; import com.pulumi.Context; import com.pulumi.Pulumi; import com.pulumi.core.Output; import com.pulumi.gcp.compute.ComputeFunctions; import com.pulumi.gcp.compute.inputs.GetDefaultServiceAccountArgs; import com.pulumi.gcp.compute.inputs.GetImageArgs; import com.pulumi.gcp.compute.InstanceTemplate; import com.pulumi.gcp.compute.InstanceTemplateArgs; import com.pulumi.gcp.compute.inputs.InstanceTemplateDiskArgs; import com.pulumi.gcp.compute.inputs.InstanceTemplateNetworkInterfaceArgs; import com.pulumi.gcp.compute.inputs.InstanceTemplateSchedulingArgs; import com.pulumi.gcp.compute.inputs.InstanceTemplateServiceAccountArgs; 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) { final var default = ComputeFunctions.getDefaultServiceAccount(); final var myImage = ComputeFunctions.getImage(GetImageArgs.builder() .family("debian-11") .project("debian-cloud") .build()); var foobar = new InstanceTemplate("foobar", InstanceTemplateArgs.builder() .machineType("e2-medium") .canIpForward(false) .tags( "foo", "bar") .disks(InstanceTemplateDiskArgs.builder() .sourceImage(myImage.applyValue(getImageResult -> getImageResult.selfLink())) .autoDelete(true) .boot(true) .build()) .networkInterfaces(InstanceTemplateNetworkInterfaceArgs.builder() .network("default") .build()) .scheduling(InstanceTemplateSchedulingArgs.builder() .preemptible(false) .automaticRestart(true) .build()) .metadata(Map.ofEntries( Map.entry("gce-software-declaration", """ { "softwareRecipes": [{ "name": "install-gce-service-proxy-agent", "desired_state": "INSTALLED", "installSteps": [{ "scriptRun": { "script": "#! /bin/bash\nZONE=$(curl --silent http://metadata.google.internal/computeMetadata/v1/instance/zone -H Metadata-Flavor:Google | cut -d/ -f4 )\nexport SERVICE_PROXY_AGENT_DIRECTORY=$(mktemp -d)\nsudo gsutil cp gs://gce-service-proxy-"$ZONE"/service-proxy-agent/releases/service-proxy-agent-0.2.tgz "$SERVICE_PROXY_AGENT_DIRECTORY" || sudo gsutil cp gs://gce-service-proxy/service-proxy-agent/releases/service-proxy-agent-0.2.tgz "$SERVICE_PROXY_AGENT_DIRECTORY"\nsudo tar -xzf "$SERVICE_PROXY_AGENT_DIRECTORY"/service-proxy-agent-0.2.tgz -C "$SERVICE_PROXY_AGENT_DIRECTORY"\n"$SERVICE_PROXY_AGENT_DIRECTORY"/service-proxy-agent/service-proxy-agent-bootstrap.sh" } }] }] } """), Map.entry("gce-service-proxy", """ { "api-version": "0.2", "proxy-spec": { "proxy-port": 15001, "network": "my-network", "tracing": "ON", "access-log": "/var/log/envoy/access.log" } "service": { "serving-ports": [80, 81] }, "labels": { "app_name": "bookserver_app", "app_version": "STABLE" } } """), Map.entry("enable-guest-attributes", "true"), Map.entry("enable-osconfig", "true") )) .serviceAccount(InstanceTemplateServiceAccountArgs.builder() .email(default_.email()) .scopes("cloud-platform") .build()) .labels(Map.of("gce-service-proxy", "on")) .build()); } } ``` ## Using with Instance Group Manager Instance Templates cannot be updated after creation with the Google Cloud Platform API. In order to update an Instance Template, this provider will create a replacement. In order to effectively use an Instance Template resource with an [Instance Group Manager resource](https://www.terraform.io/docs/providers/google/r/compute_instance_group_manager.html). Either omit the Instance Template `name` attribute, or specify a partial name with `name_prefix`. Example: ```java package generated_program; import com.pulumi.Context; import com.pulumi.Pulumi; import com.pulumi.core.Output; import com.pulumi.gcp.compute.InstanceTemplate; import com.pulumi.gcp.compute.InstanceTemplateArgs; import com.pulumi.gcp.compute.inputs.InstanceTemplateDiskArgs; import com.pulumi.gcp.compute.inputs.InstanceTemplateNetworkInterfaceArgs; import com.pulumi.gcp.compute.InstanceGroupManager; import com.pulumi.gcp.compute.InstanceGroupManagerArgs; 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 instanceTemplate = new InstanceTemplate("instanceTemplate", InstanceTemplateArgs.builder() .namePrefix("instance-template-") .machineType("e2-medium") .region("us-central1") .disks() .networkInterfaces() .build()); var instanceGroupManager = new InstanceGroupManager("instanceGroupManager", InstanceGroupManagerArgs.builder() .instanceTemplate(instanceTemplate.id()) .baseInstanceName("instance-group-manager") .zone("us-central1-f") .targetSize("1") .build()); } } ``` With this setup, this provider generates a unique name for your Instance Template and can then update the Instance Group manager without conflict before destroying the previous Instance Template. ## Deploying the Latest Image A common way to use instance templates and managed instance groups is to deploy the latest image in a family, usually the latest build of your application. There are two ways to do this in the provider, and they have their pros and cons. The difference ends up being in how "latest" is interpreted. You can either deploy the latest image available when the provider runs, or you can have each instance check what the latest image is when it's being created, either as part of a scaling event or being rebuilt by the instance group manager. If you're not sure, we recommend deploying the latest image available when the provider runs, because this means all the instances in your group will be based on the same image, always, and means that no upgrades or changes to your instances happen outside of a `pulumi up`. You can achieve this by using the `gcp.compute.Image` data source, which will retrieve the latest image on every `pulumi apply`, and will update the template to use that specific image: ```java package generated_program; import com.pulumi.Context; import com.pulumi.Pulumi; import com.pulumi.core.Output; import com.pulumi.gcp.compute.ComputeFunctions; import com.pulumi.gcp.compute.inputs.GetImageArgs; import com.pulumi.gcp.compute.InstanceTemplate; import com.pulumi.gcp.compute.InstanceTemplateArgs; import com.pulumi.gcp.compute.inputs.InstanceTemplateDiskArgs; 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) { final var myImage = ComputeFunctions.getImage(GetImageArgs.builder() .family("debian-11") .project("debian-cloud") .build()); var instanceTemplate = new InstanceTemplate("instanceTemplate", InstanceTemplateArgs.builder() .namePrefix("instance-template-") .machineType("e2-medium") .region("us-central1") .disks(InstanceTemplateDiskArgs.builder() .sourceImage(myImage.applyValue(getImageResult -> getImageResult.selfLink())) .build()) .build()); } } ``` To have instances update to the latest on every scaling event or instance re-creation, use the family as the image for the disk, and it will use GCP's default behavior, setting the image for the template to the family: ```java package generated_program; import com.pulumi.Context; import com.pulumi.Pulumi; import com.pulumi.core.Output; import com.pulumi.gcp.compute.InstanceTemplate; import com.pulumi.gcp.compute.InstanceTemplateArgs; import com.pulumi.gcp.compute.inputs.InstanceTemplateDiskArgs; 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 instanceTemplate = new InstanceTemplate("instanceTemplate", InstanceTemplateArgs.builder() .disks(InstanceTemplateDiskArgs.builder() .sourceImage("debian-cloud/debian-11") .build()) .machineType("e2-medium") .namePrefix("instance-template-") .region("us-central1") .build()); } } ``` ## Import Instance templates can be imported using any of these accepted formats ```sh $ pulumi import gcp:compute/instanceTemplate:InstanceTemplate default projects/{{project}}/global/instanceTemplates/{{name}} ``` ```sh $ pulumi import gcp:compute/instanceTemplate:InstanceTemplate default {{project}}/{{name}} ``` ```sh $ pulumi import gcp:compute/instanceTemplate:InstanceTemplate default {{name}} ``` [custom-vm-types]https://cloud.google.com/dataproc/docs/concepts/compute/custom-machine-types [network-tier]https://cloud.google.com/network-tiers/docs/overview
    • Constructor Detail

      • InstanceTemplate

        public InstanceTemplate​(java.lang.String name)
        Parameters:
        name - The _unique_ name of the resulting resource.
      • InstanceTemplate

        public InstanceTemplate​(java.lang.String name,
                                InstanceTemplateArgs args)
        Parameters:
        name - The _unique_ name of the resulting resource.
        args - The arguments to use to populate this resource's properties.
      • InstanceTemplate

        public InstanceTemplate​(java.lang.String name,
                                InstanceTemplateArgs args,
                                @Nullable
                                com.pulumi.resources.CustomResourceOptions options)
        Parameters:
        name - The _unique_ name of the resulting resource.
        args - The arguments to use to populate this resource's properties.
        options - A bag of options that control this resource's behavior.
    • Method Detail

      • advancedMachineFeatures

        public com.pulumi.core.Output<java.util.Optional<InstanceTemplateAdvancedMachineFeatures>> advancedMachineFeatures()
        Returns:
        Configure Nested Virtualisation and Simultaneous Hyper Threading on this VM. Structure is documented below
      • canIpForward

        public com.pulumi.core.Output<java.util.Optional<java.lang.Boolean>> canIpForward()
        Returns:
        Whether to allow sending and receiving of packets with non-matching source or destination IPs. This defaults to false.
      • confidentialInstanceConfig

        public com.pulumi.core.Output<InstanceTemplateConfidentialInstanceConfig> confidentialInstanceConfig()
        Returns:
        Enable [Confidential Mode](https://cloud.google.com/compute/confidential-vm/docs/about-cvm) on this VM. Structure is documented below
      • description

        public com.pulumi.core.Output<java.util.Optional<java.lang.String>> description()
        Returns:
        A brief description of this resource.
      • disks

        public com.pulumi.core.Output<java.util.List<InstanceTemplateDisk>> disks()
        Returns:
        Disks to attach to instances created from this template. This can be specified multiple times for multiple disks. Structure is documented below.
      • enableDisplay

        public com.pulumi.core.Output<java.util.Optional<java.lang.Boolean>> enableDisplay()
        Returns:
        ) Enable [Virtual Displays](https://cloud.google.com/compute/docs/instances/enable-instance-virtual-display#verify_display_driver) on this instance. **Note**: `allow_stopping_for_update` must be set to true in order to update this field.
      • guestAccelerators

        public com.pulumi.core.Output<java.util.Optional<java.util.List<InstanceTemplateGuestAccelerator>>> guestAccelerators()
        Returns:
        List of the type and count of accelerator cards attached to the instance. Structure documented below.
      • instanceDescription

        public com.pulumi.core.Output<java.util.Optional<java.lang.String>> instanceDescription()
        Returns:
        A brief description to use for instances created from this template.
      • labels

        public com.pulumi.core.Output<java.util.Optional<java.util.Map<java.lang.String,​java.lang.String>>> labels()
        Returns:
        A set of key/value label pairs to assign to instances created from this template.
      • machineType

        public com.pulumi.core.Output<java.lang.String> machineType()
        Returns:
        The machine type to create. To create a machine with a [custom type][custom-vm-types] (such as extended memory), format the value like `custom-VCPUS-MEM_IN_MB` like `custom-6-20480` for 6 vCPU and 20GB of RAM. ***
      • metadata

        public com.pulumi.core.Output<java.util.Optional<java.util.Map<java.lang.String,​java.lang.Object>>> metadata()
        Returns:
        Metadata key/value pairs to make available from within instances created from this template.
      • metadataFingerprint

        public com.pulumi.core.Output<java.lang.String> metadataFingerprint()
        Returns:
        The unique fingerprint of the metadata.
      • metadataStartupScript

        public com.pulumi.core.Output<java.util.Optional<java.lang.String>> metadataStartupScript()
        Returns:
        An alternative to using the startup-script metadata key, mostly to match the compute_instance resource. This replaces the startup-script metadata key on the created instance and thus the two mechanisms are not allowed to be used simultaneously.
      • minCpuPlatform

        public com.pulumi.core.Output<java.util.Optional<java.lang.String>> minCpuPlatform()
        Returns:
        Specifies a minimum CPU platform. Applicable values are the friendly names of CPU platforms, such as `Intel Haswell` or `Intel Skylake`. See the complete list [here](https://cloud.google.com/compute/docs/instances/specify-min-cpu-platform).
      • name

        public com.pulumi.core.Output<java.lang.String> name()
        Returns:
        The name of the instance template. If you leave this blank, the provider will auto-generate a unique name.
      • namePrefix

        public com.pulumi.core.Output<java.lang.String> namePrefix()
        Returns:
        Creates a unique name beginning with the specified prefix. Conflicts with `name`.
      • networkInterfaces

        public com.pulumi.core.Output<java.util.Optional<java.util.List<InstanceTemplateNetworkInterface>>> networkInterfaces()
        Returns:
        Networks to attach to instances created from this template. This can be specified multiple times for multiple networks. Structure is documented below.
      • networkPerformanceConfig

        public com.pulumi.core.Output<java.util.Optional<InstanceTemplateNetworkPerformanceConfig>> networkPerformanceConfig()
        Returns:
        (Optional, Configures network performance settings for the instance created from the template. Structure is documented below. **Note**: `machine_type` must be a [supported type](https://cloud.google.com/compute/docs/networking/configure-vm-with-high-bandwidth-configuration), the `image` used must include the [`GVNIC`](https://cloud.google.com/compute/docs/networking/using-gvnic#create-instance-gvnic-image) in `guest-os-features`, and `network_interface.0.nic-type` must be `GVNIC` in order for this setting to take effect.
      • project

        public com.pulumi.core.Output<java.lang.String> project()
        Returns:
        The ID of the project in which the resource belongs. If it is not provided, the provider project is used.
      • region

        public com.pulumi.core.Output<java.lang.String> region()
        Returns:
        An instance template is a global resource that is not bound to a zone or a region. However, you can still specify some regional resources in an instance template, which restricts the template to the region where that resource resides. For example, a custom `subnetwork` resource is tied to a specific region. Defaults to the region of the Provider if no value is given.
      • reservationAffinity

        public com.pulumi.core.Output<java.util.Optional<InstanceTemplateReservationAffinity>> reservationAffinity()
        Returns:
        Specifies the reservations that this instance can consume from. Structure is documented below.
      • resourcePolicies

        public com.pulumi.core.Output<java.util.Optional<java.lang.String>> resourcePolicies()
        Returns:
        - A list of self_links of resource policies to attach to the instance. Modifying this list will cause the instance to recreate. Currently a max of 1 resource policy is supported.
      • scheduling

        public com.pulumi.core.Output<InstanceTemplateScheduling> scheduling()
        Returns:
        The scheduling strategy to use. More details about this configuration option are detailed below.
      • selfLink

        public com.pulumi.core.Output<java.lang.String> selfLink()
        Returns:
        The URI of the created resource.
      • selfLinkUnique

        public com.pulumi.core.Output<java.lang.String> selfLinkUnique()
        Returns:
        A special URI of the created resource that uniquely identifies this instance template with the following format: `projects/{{project}}/global/instanceTemplates/{{name}}?uniqueId={{uniqueId}}` Referencing an instance template via this attribute prevents Time of Check to Time of Use attacks when the instance template resides in a shared/untrusted environment.
      • serviceAccount

        public com.pulumi.core.Output<java.util.Optional<InstanceTemplateServiceAccount>> serviceAccount()
        Returns:
        Service account to attach to the instance. Structure is documented below.
      • shieldedInstanceConfig

        public com.pulumi.core.Output<InstanceTemplateShieldedInstanceConfig> shieldedInstanceConfig()
        Returns:
        Enable [Shielded VM](https://cloud.google.com/security/shielded-cloud/shielded-vm) on this instance. Shielded VM provides verifiable integrity to prevent against malware and rootkits. Defaults to disabled. Structure is documented below. **Note**: `shielded_instance_config` can only be used with boot images with shielded vm support. See the complete list [here](https://cloud.google.com/compute/docs/images#shielded-images).
      • tags

        public com.pulumi.core.Output<java.util.Optional<java.util.List<java.lang.String>>> tags()
        Returns:
        Tags to attach to the instance.
      • tagsFingerprint

        public com.pulumi.core.Output<java.lang.String> tagsFingerprint()
        Returns:
        The unique fingerprint of the tags.
      • get

        public static InstanceTemplate get​(java.lang.String name,
                                           com.pulumi.core.Output<java.lang.String> id,
                                           @Nullable
                                           InstanceTemplateState state,
                                           @Nullable
                                           com.pulumi.resources.CustomResourceOptions options)
        Get an existing Host resource's state with the given name, ID, and optional extra properties used to qualify the lookup.
        Parameters:
        name - The _unique_ name of the resulting resource.
        id - The _unique_ provider ID of the resource to lookup.
        state -
        options - Optional settings to control the behavior of the CustomResource.