Develop custom solutions with Deployment Manager templates

Google Cloud Deployment Manager allows you to specify all the resources needed for your application in a declarative format using YAML. You can also use Python or Jinja2 templates to parameterize the configuration. By creating configuration files which define your solution resources, the process of creating your resources can be repeated over and over with consistent results. This page describes how to build templates for use with Google Cloud Marketplace. For more information about using Deployment Manager to build templates, see the Google Cloud Deployment Manager documentation.

GCP Marketplace deployment package

GCP Marketplace uses Deployment Manager to instantiate partner solutions. To support GCP Marketplace's UI interface, automated testing, and other functionality, there are some key requirements for your package. These requirements are described on this page.

Single top-level template

Although Deployment Manager allows configs to specify multiple top-level resources or templates, GCP Marketplace requires all resources to be wrapped in a single top-level template file. The top-level template can instantiate any number of resources and sub-templates. The top-level template also exposes all the user-visible configuration properties.

Directory structure

The following files and directory structure are required. Together, these files are referred to as the deployment package:

root/
   <solution name>.{py|jinja}
   <solution name>.{py|jinja}.schema
   <solution name>.{py|jinja}.display
   test_config.yaml
   resources/
      <language>/
         <logo filename>.png

Each of these required files is described in detail in the sections below. In addition, the deployment package will typically contain sub-templates and other dependencies of the top-level template.

Templates

The purpose of a Deployment Manager template is to accept a set of user-configurable properties and "expand" into a Deployment Manager config, which is an explicit list of resources and all of their properties to be included in the deployment. Deployment Manager supports two types of templates based on Python and Jinja2. For more information, see Adding Templates in the Deployment Manager documentation.

Common templates

Google provides a set of helper templates for use in your solution. These helpers make it easier to follow standard patterns and defaults when creating common resources like virtual machine instances, and manipulating input parameters in various ways. These templates are available in GitHub so that you can include them in your deployment package and continue to develop them. The following list provides brief descriptions of a few of the most used template files:

  • default.py—defines constants used by all other modules.
  • common.py—contains useful methods for input manipulation. For example, the method MakeGlobalComputeLink will take an image name and, based on the Deployment Manager context, converts it to the resource link. For example, https://www.googleapis.com/compute/v1/projects/debian-cloud/global/images/debian-7-wheezy-v20140619.
  • password.py—generates random passwords. Solutions with admin portals should be protected by a random initial password.
  • vm_instance.py—sets all the typical defaults for a single instance and allows you to create multiple disks alongside it.
  • vm_multiple_instances.py—enables you to easily create a configurable cluster composed of multiple copies of the same instance type.

When using these helpers, you should add them to a subdirectory named "common" in your deployment package:

root/
   <solution name>.{py|jinja}
   common/
      default.py
      vm_instance.py
      ...

Schema file

Deployment Manager schema files declare the input properties of a template using a language called JSON Schema. Schema files must have the same name as their corresponding template, with the addition of the .schema suffix. For GCP Marketplace solutions, the top-level template is required to have an associated schema file. It is also recommended to include schema files for sub-templates defined in the deployment package. For more information, see Using Schemas in the Deployment Manager documentation.

The following code is an example schema file. The schema fields are described below the example.

imports:
  - path: example.jinja
  - name: common.py
    path: common/default.py

info:
  version: 1.0
  title: Example

required:
  - foo
  - baz

properties:
  foo:
    type: string
    default: Foo
    enum:
      - BLUE
      - GREEN
      - RED
  bar:
    type: integer
    minimum: 0

  baz:
    type: string
    x-googleProperty:
      type: GCE_ZONE

Imports

This section is not part of the JSON Schema spec. It is a mechanism that is specific to Deployment Manager for importing templates and other file dependencies required by the template associated with the schema.

Info

This section is not part of the JSON Schema spec. It is ignored by GCP Marketplace. Instead, user-visible descriptive information is provided in the display file, described below.

Required

This field is part of the JSON Schema specification. It lists properties that must have a non-null value in the final configuration.

We recommend that required properties have a default value, so that the user (the consumer of your solution) won't have to explicitly change the value. However, if you need the user to explicitly set the property, then you should not supply a default. For required properties that do not have a default, we recommend that you add placeholder text in the display file, described below.

Properties

This field is also part of the JSON Schema specification. It declares the set of properties that can be passed into the template, and the JSON Schema enforced validation for each property.

The validation will be enforced by Deployment Manager at deployment time, but the same validation is also used to generate the configuration UI interface. For example, if the property type is integer, the input field will enforce integer values. If the integer has a minimum of 0, then the UI widget will show an error for negative values. Properties with an enum validation will show a drop-down selection widget instead of a text input. Properties with type boolean will show a check box widget.

Properties in the schema may also include an x-googleProperty extension to indicate that the property corresponds to a Google-specific property, such as a zone or machine type. The extensions are explained in detail below, in Parameterizing the solution.

Display file

The display file is a YAML file containing user-visible strings that will appear in various UIs. GCP Marketplace solutions require a display file for the top-level template. The display file should have the same name as the top-level template with the addition of a .display suffix.

The following sections describe the display file structure.

Description

The description section contains general descriptive information about the template, such as the user-visible title, author information, marketing website, documentation links, and so on.

Input

The input section contains information about how the template's input properties should be presented in a configuration form. It is used to organize properties into sections and to assign each property a user-visible title, as well as other optional text such as tooltips, validation error text, placeholder text (in the case of properties with no default value).

Runtime

The runtime section contains information that is displayed on a running instance of the template. This is where we present the user with a table of label/value pairs, a list of required and suggested action items, primary and secondary action buttons, and so on. Unlike the other sections, most fields under runtime accept dynamic expressions that are evaluated against the running instance. This can be used, for example, to show the user the current value of an ephemeral IP address assigned to a virtual machine instance, which may change after the initial deployment.

Test_config.yaml

This file, with the required name "test_config.yaml", is required for GCP Marketplace solutions. It provides a standard mechanism for validating solutions out of the box, both for end-users and for the GCP Marketplace internal validation processes. The solution must deploy successfully with the following command:

gcloud deployment-manager deployments create <deployment-name> --config=path/to/test_config.yaml

The following is an example test_config.yaml file:

imports:
- path: example.jinja

resources:
- name: example
  type: example.jinja
  properties:
    myRequiredPropertyWithNoDefault: 'user@example.com'

The imports section contains a single import, pointing to the location of the top-level template. All other import dependencies should be declared in the top-level templates schema file.

The resources section contains a single resource with an arbitrary name and the type corresponding to the top-level template. The properties section may be empty or omitted. The only time it is required is when the top-level template contains required properties which do not have a default value. In those cases, some valid value for the required property must be provided.

Logos

You need to provide three graphics for your solution, as described in the following table.

Logo name Requirements Usage
Solution logo medium 130 x 130 px PNG or JPEG format with a transparent background Logo appears on your solution details page and on the deployment input page.
Solution icon 64 x 64 px PNG or JPEG format with a transparent background
(Must be scalable to 16x16. Should be graphical and occupy most or all of the image. Text and very narrow horizontal images don't work well.)
Used as an icon on the resource tree of the Deployment Manager UI.
Architecture diagram 450 x 450 px PNG or JPEG format Optional, appears only on the deployment input page

Deployment functionality: solution policies

This section describes the following solution policies:

  • Firewalls
  • Passwords
  • Static IPs
  • Software installation status
  • Default and additional scope
  • Modifying the boot disk

Firewalls

If certain ports on your solution are intended to be exposed to the public internet (for example, HTTP(S)), then it could be acceptable to open these ports by default. However, if some post-deploy setup is required to make the port secure, we recommend leaving the port closed by default and providing instructions in post-deploy on how to open the port.

For example, for admin consoles you should protect ports because leaving them exposed allows an attacker to potentially hijack the solution. In that case, we recommend generating a random initial password. Otherwise, you should leave the port closed and provide instructions for users on how to tunnel from localhost.

Passwords

If your application has a dashboard, database, or management console that requires a login, then your application should be customized through a server script to read user login credentials from the instance metadata and set up the username and temporary password as part of the deployment.

To generate a password use the following lines in the <solution>.jinja file.

- name: generated-password
  type: password.py
  properties:
    length: 12
    includeSymbols: False

We also recommend that you add a suggested Next step for your users so that they change their password (along with instructions on how to do so).

An alternative (as discussed above in Firewalls) is to close any firewalls by default and have the user perform special setup tasks before opening the ports. Special password setup should be described to the user in the Next steps section of your solution's post-deploy UI.

Static IPs

Because users usually have restrictions on their quota of static IPs, assignment of static IPs might cause deployment failures and is not recommended during instance deployment. Instead, we recommend that you use ephemeral IPs and provide instructions for your users on how to promote ephemeral IPs to static IPs post-deployment. Otherwise, you can configure your solution to add static IPs, but in that case, you must include a config option to disable it. For more information, see Promoting an ephemeral external IP address.

Because ephemeral IPs might change after deployment, if you intend to show the user the ephemeral IP in the post-deploy information, you need to invoke the externalIp() function. For more information about the externalIp() function, see Post-deployment solution UI configuration, below.

Software installation status

By default, a virtual machine instance is considered completely created when it starts the guest OS boot process. However, additional steps (such as downloading, installing, and configuring software) can take many additional minutes. To provide the best user experience, solution deployments should incorporate awareness of these software installation and initialization steps, and should not finish until they have completed. This is especially true if metadata or Next Steps provide links that require software on a newly-deployed instance to be available, such as an administrative console.

Solutions can use the DM RuntimeConfig API Waiter resource to represent the additional step of software initialization. When included in a deployment, a Waiter resource will block the deployment from succeeding until it receives an appropriate signal from a third-party source, such as a startup script running on the instance. The Waiter should be given a name that indicates its purpose, such as "my-deployment-software-installation".

To enable software installation status in a deployment, do the following:

  • Add the https://www.googleapis.com/auth/cloudruntimeconfig authentication scope to instances in the deployment.
  • Add a RuntimeConfig resource and a Waiter resource to the deployment.
  • Add startup logic to the instance image to create a Variable resource and signal the Waiter.

For more information, you can refer to this example in the Deployment Manager Samples GitHub repository.

Default and additional instance access scopes

When building a solution, often you need the instances to have the capability to talk to other Google services. For example, they might need to read data stored in Google Cloud Storage. You can accomplish this through a combination of enabling a service account to be used in the instance, and enabling specific scopes to be tied to the instance.

The fact to keep in mind is that after an instance has been created with a set of access scopes, you cannot change the scopes for that instance. Therefore, even if you don't foresee the instance talking to other services, in most cases, you should at least enable the following default access scopes:

  • Read-only access to Google Cloud Storage: https://www.googleapis.com/auth/devstorage.read_only
  • Write access to the Compute Engine log: https://www.googleapis.com/auth/logging.write

In situations where you want to enable additional scopes (for example, Google Compute API access), you should contact your assigned Partner Engineer to request permission to add the scope.

Boot and data disk recommendations

The boot disk for each virtual machine instance is created from a partner provided instance image. The default configuration of the boot disk should be the same size as the instance image. If the boot disk is configured to be smaller than the image, the deployment will fail. If the boot disk is configured to be larger than the image, the user will see a warning: "You might need to resize the root partition manually if the operating system does not support automatic resizing." Unfortunately, this message currently appears regardless of which operating system is installed.

For many solutions, there is no reason to allow the user to modify the boot disk. If the solution is not writing any significant quantity of data to the boot disk, then the boot disk properties should be removed.

As a best practice, we recommend that you attach a secondary data disk for any persistent user state. Following this best practice allows the user to more easily upgrade the solution by simply swapping in an upgraded virtual machine instance (based on a new source image). If your solution follows this practice, you should typically expose size and type properties for the data disk, but not the boot disk.

On the other hand, if the solution does rely on writing significant amounts of data to the boot disk, it should expose size and type properties for the boot disk, following these conventions:

  • The minimum and default size of the disk should match the image size.
  • The default type should be either pd-standard or pd-ssd, depending on which is more appropriate.
  • Both properties should be marked as advanced in the display file.

Parameterizing the solution

You can customize a solution template to expose specific properties for the user to configure before deploying a solution. To use a UI widget, you attach an extension called x-googleProperty to the property in the schema. These properties define the UI widgets numbered (in red) in the following graphic.

Below is the list of supported UI widgets. Each description specifies the x-googleProperty to use, its dependencies, the UI widget that it surfaces, and an example.

Zone (1)

  • x-googleProperty type: GCE_ZONE
  • UI widget: a selector widget listing all the zones available in the user’s project
  • Default: you can give this property a default value that will be pre-selected when the UI loads

Example:

properties:
  zone:
    type: string
    x-googleProperty:
      type: GCE_ZONE

Machine type (2)

  • x-googleProperty type: GCE_MACHINE_TYPE
  • Dependency: Zone (machine types are scoped by zone)
  • UI widget: a selector widget listing all the machine types available in the user’s project and selected zone
  • Default: you can give this property a default value that will be pre-selected when the UI loads
  • Optional: minimum CPU and RAM requirements can be specified

Example:

properties:
  machineType:
    type: string
    x-googleProperty:
      type: GCE_MACHINE_TYPE
        zoneProperty: zone
        gceMachineType:
        minCpu: 1
        minRamGb: 3.5

Disk type (3)

  • x-googleProperty type: GCE_DISK_TYPE
  • Dependency: Zone
  • UI widget: a selector widget listing all the disk types available in the user’s project and selected zone

Example:

properties:
  diskType:
    type: string
    x-googleProperty:
      type: GCE_DISK_TYPE
        zoneProperty: zone

Disk size (4)

  • x-googleProperty type: GCE_DISK_SIZE
  • Dependency: Disk type
  • UI widget: an input field with validation rules for minimum and maximum values

Example:

properties:
  diskSize:
    type: integer
    x-googleProperty:
      type: GCE_DISK_SIZE
        gceDiskSize:
          diskTypeProperty: diskType

Network (5)

  • x-googleProperty type: GCE_NETWORK
  • UI widget: a selector widget listing all the networks available in the user’s project

Example:

properties:
  network:
    type: string
    x-googleProperty:
      type: GCE_NETWORK

Subnetwork (6)

Subnet mode is a form of networks in which your network is subdivided into regional subnetworks. Each subnetwork controls the IP address range used for instances that are allocated to that subnetwork. For more information, see the documentation on Subnetworks.

  • Dependencies:
    • Network (each subnetwork has a parent network it belongs to)
    • Zone (each subnetwork belongs to a region)
  • Constraints: The subnetwork property must be optional; it cannot be included in the Required section. This is to ensure the solution is deployable in legacy projects that don't have subnetworks.

Example:

properties:
  subnetwork:
    type: string
    x-googleProperty:
      type: GCE_SUBNETWORK
      zoneProperty: zone
        gceSubnetwork:
          networkProperty: network
  zone:
    type: string
    x-googleProperty:
      type: GCE_ZONE
  network:
    type: string
    x-googleProperty:
      type: GCE_NETWORK

Post-deployment solution UI configuration

The post-deployment UI of your solution is configured mainly by runtime metadata. This section describes the metadata, the UI components it applies to, and provides an example of what your runtime metadata might look like.

Post-deployment solution UI functions

The following functions can be called from the post-deployment solution UI.

  • properties() Returns a JSON object representing the fully expanded properties of the resource.

  • outputs() For template resources, returns a JSON object representing the fully expanded outputs of the template.

  • consoleUrl(resourceUrl) Returns a Console URL for the given resource. Throws an exception if the type of the resource URL is not recognized, or there is no console details page for that type.

  • externalIp(outputs().vmSelfLink) Returns the live IP address of the instance, given its self link.

Additionally, any of the strings above can be shown conditionally using showIf expression, for example:

suggestedActions:
    - heading: Allow HTTP traffic on your server
      showIf: '{{ !properties().enableTcp80 }}'

Post-deployment solution UI sections

The UI contains three main sections, as shown (numbered in red) in the following graphic.

The following properties define the UI.

Application table (1)

A table of label value pairs that display basic information such as the application URL, admin URL, user name, initial password, and so on.

Action buttons (2)

Buttons enable actions such as using SSH to connect to a virtual machine image, or linking to a resource details page (or other URL).

Action items (3)

A bulleted list of steps the user might want to complete after deployment. Each item might have a heading, description, and code snippet. Two common types of action items:

  • requiredActions: A list of required one-time actions. For example, a prompt for a user to change the generated password.
  • suggestedActions: A list of suggested actions. For example, instructions on how to open the firewall rule, as shown below.
suggestedActions:
    - heading: Allow HTTP traffic on your server
      description:
        To allow specific network traffic from the Internet,
        create a firewall rule to open the TCP port 80
      snippet:
        gcloud --project={{ outputs().project }} compute firewall-rules create "{{ outputs().deployment }}-tcp-80" --network {{ properties().network }} --allow tcp:80 --target-tags "{{ outputs().deployment }}-tcp-80"

Full runtime metadata example

runtime:
  applicationTable:
    rows:
      - label: Instance zone
        value: '{{ properties().zone }}'
      - label: Site address
        value: '<a href="http://{{ externalIp(outputs().vmSelfLink) }}/">http://{{ externalIp(outputs().vmSelfLink) }}/</a>'
      - label: Admin user
        value: user
      - label: Admin password (Temporary)
        value: '{{ outputs().password }}'
      - label: Instance
        value: '<a href="{{ consoleUrl(outputs().vmSelfLink) }}">{{ outputs().vmName }}</a>'

 primaryButton:
    label: Log into the admin panel
    type: TYPE_URL
    action: 'http://{{ externalIp(outputs().vmSelfLink) }}/wp-admin/'

 secondaryButton:
    type: TYPE_GCE_VM_SSH
    label: SSH to initial primary server
    action: '{{ outputs().vmSelfLink }}'

 suggestedActions:
    - heading: Assign a static external IP address to your virtual machine instance
      description: 'An ephemeral external IP address has been assigned to the instance. If you require a static external IP address, you may promote the address to static. <a href="https://cloud.google.com/compute/docs/instances-and-network#promote_ephemeral_ip">Learn more</a>'
   -  heading: Allow HTTP traffic on your server
      description: To allow specific network traffic from the Internet, create a firewall rule to open the TCP port 80
      snippet:
        gcloud --project={{ outputs().project }} compute firewall-rules create "{{ outputs().deployment }}-tcp-80" --network {{ properties().network }} --allow tcp:80 --target-tags "{{ outputs().deployment }}-tcp-80"

Uploading the templates

Use Partner Portal to upload the templates into your solution, as described at Creating a multi-VM or custom solution.

Test the solution

There are two parts to testing: deployment testing and application testing. Each is explained in this section.

Deployment testing

Deployment testing can be done with gcloud or in Partner Portal.

Testing with gcloud

To test and verify your deployment with gcloud, follow instructions in the Deployment Manager documentation. In addition to gcloud output, you can see the post-deploy screen in GCP Marketplace that shows the results of the deployment.

Application testing with Partner Portal

After your templates are uploaded to Partner Portal, you can preview your solution. You should be able to walk through the whole deployment flow in the UI using the launch wizard. This phase also involves ensuring the application is working as intended on Google Cloud Platform.

Оцените, насколько информация на этой странице была вам полезна:

Оставить отзыв о...

Текущей странице
GCP Marketplace