Design composite templates

Composite templates in Application Design Center let you build complex applications by connecting reusable standard application templates and individual components. A modular design lets teams develop building blocks in parallel and update individual blocks without redeploying the entire application. You can also assign distinct service accounts to restrict deployment permissions for each building block. In addition, composite templates let you model and package units of deployment for a SaaS offering in App Lifecycle Manager.

Before you begin

To perform the tasks in this document, ask your administrator to grant you the necessary roles on the app-enabled folder or management project, as listed in the following table:

Task Required roles
Create, design, and edit composite templates Application Design Center Admin (roles/designcenter.admin), or
Application Design Center User (roles/designcenter.user)
Publish or share composite templates to a catalog Application Design Center Admin (roles/designcenter.admin)

For more information about roles, see Access control with IAM.

To use your own standard application templates as building blocks, set input and output variables to establish configurable variables, and create connections between your application templates. For details, see the following:

Create a composite application template

Create composite templates when you want to design and share complex applications. You can add and connect the following in your template design:

  • Standard application templates: Select from the following existing templates:

  • Components: Select from the following Google Cloud resources:

Specify template details

Template details help you categorize your template and help developers decide whether to use your template.

To enter details for your template, do the following:

Design canvas

  1. From the navigation menu, click Templates.

    Go to Templates

  2. From the Region list, select the location for the template. If you plan to create a scaled deployment in App Lifecycle Manager, select global.

  3. From the Create Template list, select Composite template.

  4. The Template ID field is automatically populated. Alternatively, enter a unique identifier for the template. This field is required.

  5. In the Template Name field, enter a human-readable identifier to display in the Google Cloud console.

    If you don't provide a name, the Template ID is copied to this field.

  6. In the Description field, enter a brief explanation of the application's purpose.

  7. Click Create template. The design canvas is displayed.

gcloud CLI

Create a new composite application template.

gcloud design-center spaces application-templates create APPLICATION_TEMPLATE \
--project=PROJECT \
--location=LOCATION \
--space=SPACE \
--display-name=DISPLAY_NAME \
--description=DESCRIPTION \
--composition-type=COMPOSITE

Replace the following:

  • APPLICATION_TEMPLATE: The template ID for the application template that you want to create.
  • PROJECT: Your management project ID.
  • LOCATION: The application template region. If you plan to create a scaled deployment in App Lifecycle Manager, use global.
  • SPACE: Your space ID.
  • DISPLAY_NAME: A name to display in the Google Cloud console.
  • DESCRIPTION: A brief description.

For more information, see gcloud design-center spaces application-templates create.

Design your template

Design your composite template by adding and connecting standard application templates and components to the following starting points:

As you design your template, App Design Center generates Terraform code to reflect the design and configuration details.

To design your template, do the following:

Design canvas

  1. From the design canvas, select Design to view the canvas.

  2. Do one of the following to get started:

    • To start from a Google-provided template, in the Get Started area on the canvas, click the template name.

    • To start from a blank canvas, continue to the next step.

  3. To add a standard application template to the canvas, do the following:

    1. In the Components area, click Embed templates.

    2. To add an existing template, click a template in one of the following lists:

      • Templates: standard application templates that are in your space's catalog, or have been shared with your space.
      • Google templates: standard application templates created by Google and added to the Google catalog.
    3. To add the selected template to the canvas, click Select.

  4. To create a new standard application template, click Create a new template. The Create new template page opens.

    For more information, see Design standard application templates.

  5. To add a component to the canvas, from the Components area, click a component.

  6. To create a communication channel between templates and components, do one of the following:

    • Drag from a blue dot on one building block to a blue dot on another building block.

    • To add a connected component to an existing component, click Add and select the component to add.

    For connection details, see the configuration documentation for each supported resource.

  7. To remove a building block or connection, do the following:

    1. In the canvas, click the building block or connection.

    2. In the Configuration area, click Delete.

    3. In the field, enter delete.

    4. Click Delete.

gcloud CLI

  1. Identify the template revision URIs for the building blocks in your space's catalog.

    gcloud design-center spaces shared-templates list \
    --project=PROJECT \
    --location=LOCATION \
    --space=SPACE
    

    Replace the following:

    • PROJECT: Your management project ID.
    • LOCATION: The application template region.
    • SPACE: Your space ID.

    For more information, see gcloud design-center spaces shared-templates list.

  2. Identify the template revision URIs for the Google catalog building blocks that you want to add to the template.

    gcloud design-center spaces shared-templates list \
    --google-catalog \
    --location=us-central1
    

    For more information, see gcloud design-center spaces shared-templates list.

  3. Add a standard application template or component to your composite template.

    gcloud design-center spaces application-templates components create COMPONENT \
    --project=PROJECT \
    --location=LOCATION \
    --space=SPACE \
    --application-template=APPLICATION_TEMPLATE \
    --shared-template-revision-uri=SHARED_TEMPLATE_URI
    

    Replace the following:

    • COMPONENT: The ID for the standard application template or component that you want to add to the template.
    • PROJECT: Your management project ID.
    • LOCATION: The application template region.
    • SPACE: Your space ID.
    • APPLICATION_TEMPLATE: The template ID for the composite application template where you're adding the standard application template or component.
    • SHARED_TEMPLATE_URI: The standard application template or component shared template URI. For example, projects/my-project/locations/us-central1/spaces/my-space/sharedTemplates/my-shared-template/revisions/rev1.

    For more information, see gcloud design-center spaces application-templates components create.

  4. Add a second standard application template or component to your template.

    gcloud design-center spaces application-templates components create COMPONENT_2 \
    --project=PROJECT \
    --location=LOCATION \
    --space=SPACE \
    --application-template=APPLICATION_TEMPLATE \
    --shared-template-revision-uri=SHARED_TEMPLATE_URI_2
    

    Replace the following:

    • COMPONENT_2: The ID for the second standard application template or component that you want to add to the template.
    • PROJECT: Your management project ID.
    • LOCATION: The application template region.
    • SPACE: Your space ID.
    • APPLICATION_TEMPLATE: The template ID for the composite template where you're adding the standard application template or component.
    • SHARED_TEMPLATE_URI_2: The second standard application template or component shared template URI. For example, projects/my-project/locations/us-central1/spaces/my-space/sharedTemplates/my-shared-template/revisions/rev1.

    For more information, see gcloud design-center spaces application-templates components create.

  5. Create a connection between the standard application templates or components.

    gcloud design-center spaces application-templates components connections create CONNECTION \
    --project=PROJECT \
    --location=LOCATION \
    --space=SPACE \
    --application-template=APPLICATION_TEMPLATE \
    --component=COMPONENT \
    --destination-component-uri=COMPONENT_2
    

    Replace the following:

    • CONNECTION: The connection ID for the connection that you want to add to the template.
    • PROJECT: Your management project ID.
    • LOCATION: The application template region.
    • SPACE: Your space ID.
    • APPLICATION_TEMPLATE: The template ID for the application template where you're adding the connection.
    • COMPONENT: The source standard application template or component ID.
    • COMPONENT_2: The destination standard application template or component ID.

    For more information, see gcloud design-center spaces application-templates components connections create.

Configure default values for components

For each component you add to a template, you can specify default configuration details, such as the resource's project and deployment location. Application Design Center applies these defaults when an application is created from this template.

Application developers can also modify connection details if the default configuration doesn't meet their requirements. For example, you might modify environment variable key names, change connection ports, or add additional roles to service accounts when you create an application.

Before developers deploy an application, they can view and modify the default values you configured in the template. Developers must configure the required details for each supported resource.

To configure components and connections, do the following:

Design canvas

  1. From the design canvas, click a component.

  2. In the Configuration area, from the Project ID list, select the project where you want to deploy the resource. Select a project with the following qualifications:

  3. Configure additional settings for the resource. For example, for Cloud SQL, you might configure the following:

    • Region
    • Backup configuration
    • Database flags
    • IP configuration

    For links to configuration documentation for each component, see Supported resources.

  4. When you connect components on the design canvas, default configuration values are used to create the connection. To add or modify connection details, do the following.

    1. In the design canvas, click the connection between two components. The Connection panel opens and displays connection parameters.

    2. Do one of the following:

      • To modify an existing connection parameter, click Edit.

      • To add a new connection parameter, click Add parameter.

    3. Update the Key and Value fields. For example, you might want to modify the following details:

      • The environment variable key names to align with your application requirements.
      • The connection port value.
      • The roles added to a service account.
  5. Click Save.

gcloud CLI

  1. Describe each component in the application template to view component parameters.

    gcloud design-center spaces application-templates components describe COMPONENT \
    --project=PROJECT \
    --location=LOCATION \
    --space=SPACE \
    --application-template=APPLICATION_TEMPLATE
    

    Replace the following:

    • COMPONENT: The component ID for the component that you want to describe.
    • PROJECT: Your management project ID.
    • LOCATION: The application template region.
    • SPACE: Your space ID.
    • APPLICATION_TEMPLATE: The template ID for the application template.

    For more information, see gcloud design-center spaces application-templates components describe.

  2. For each component you want to modify, create a JSON file in your home directory containing the parameter values.

    For example, you might create the following file for a Cloud Run component:

      [
          {
            "key": "service_name",
            "value": "frontend-service"
          },
          {
            "key": "project_id",
            "value": "DEPLOYMENT_PROJECT"
          }
      ]
    
  3. Update each component in the application template to configure the required parameters.

    gcloud design-center spaces application-templates components update COMPONENT \
    --project=PROJECT \
    --location=LOCATION \
    --space=SPACE \
    --parameters=PARAMETERS_FILE_PATH \
    --application-template=APPLICATION_TEMPLATE
    

    Replace the following:

    • COMPONENT: The component ID for the component that you want to update.
    • PROJECT: Your management project ID.
    • LOCATION: The application template region.
    • SPACE: Your space ID.
    • PARAMETERS_FILE_PATH: A JSON file that includes component parameters.
    • APPLICATION_TEMPLATE: The template ID for the application template.

    For more information, see gcloud design-center spaces application-templates components update.

  4. Describe the component connections.

    gcloud design-center spaces application-templates components connections describe CONNECTION \
    --component=COMPONENT \
    --application-template=APPLICATION_TEMPLATE \
    --project=PROJECT \
    --location=LOCATION \
    --space=SPACE
    

    Replace the following:

    • CONNECTION: The connection ID.
    • COMPONENT: The component ID.
    • APPLICATION_TEMPLATE: The template ID.
    • PROJECT: Your management project ID.
    • LOCATION: The application template region.
    • SPACE: Your space ID.

    For more information, see gcloud design-center spaces application-templates components connections describe.

  5. Edit component connection parameters.

    gcloud design-center spaces application-templates components connections update CONNECTION \
        --component=COMPONENT \
        --application-template=APPLICATION_TEMPLATE \
        --project=PROJECT \
        --location=LOCATION \
        --space=SPACE \
        --source-component-parameters='[{"key": "SOURCE_KEY", "value": "SOURCE_VALUE"}]'
    

    Replace the following:

    • CONNECTION: The connection ID.
    • COMPONENT: The component ID.
    • APPLICATION_TEMPLATE: The template ID.
    • PROJECT: Your management project ID.
    • LOCATION: The application template region.
    • SPACE: Your space ID.
    • SOURCE_KEY: The new parameter key.
    • SOURCE_VALUE: The new parameter value.

    For more information, see gcloud design-center spaces application-templates components connections update.

Configure standard application templates

When developers deploy your composite template as an application, an application is created for each of the following:

  • Each group of standard application templates.
  • Each group of components.

You can provide default values for each group. For example, you might include the deployment project, region, and owners. When developers deploy the application in App Design Center, they can use the default values, or specify their own details for each application.

To provide default application details for each group, do the following:

Design canvas

  1. From the design canvas, click a standard application template.

    The Embedded Template panel opens.

  2. In the Configuration area, enter the application details.

    For more information, see Create an application draft.

gcloud CLI

For more information, see Design your template.

Prevent variable name collisions

Multiple components or standard application templates in a composite template might contain the same variable names. For example, a database and an application service might both require a project_id variable. When a developer deploys an application, the variable value that they specify is used for every instance of a repeated variable name.

To prevent variable name collisions, you can map a component's variable name to a unique alias on the composite template. For example, you might map project_id to database_project_id for a database component and service_project_id for a service component.

Validation rules for variable aliases

Make sure that your variable aliases meet the following requirements:

  • You can only create variable aliases for composite application templates (--composition-type=COMPOSITE).

  • The aliased variable must exist in the component and be exposed as a template input variable. By default, templates expose required component variables. If a variable is optional, you must first add it as a template input variable before you set an alias for it.

  • Variable names and alias names must be non-empty strings.

  • You can only alias each variable once within a component.

  • If multiple variables share an alias, the variables must have compatible data types.

Configure variable aliases using gcloud CLI

To configure variable aliases when you add a component to a composite template, or to update aliases on an existing component, use the following gcloud CLI commands. If a variable is optional, you must first add it as a template input variable before you set an alias for it.

After you configure variable aliases, the composite template uses the aliases for those template input variables. When developers create an application draft from the composite template, the input fields display the alias names. When developers specify deployment parameters or unit configurations for SaaS offerings, they set values using the alias keys.

Add aliases when creating a component

To set variable aliases when adding a component or standard application template to a composite template, use the following command:

gcloud design-center spaces application-templates components create \
    COMPONENT \
    --project=PROJECT \
    --location=LOCATION \
    --space=SPACE \
    --application-template=APPLICATION_TEMPLATE \
    --shared-template-revision-uri=SHARED_TEMPLATE_URI \
    --input-variable-aliases=variable=VARIABLE_NAME,alias=ALIAS_NAME

Replace the following:

  • COMPONENT: The ID for the standard application template or component that you want to add to the template.

  • PROJECT: Your management project ID.

  • LOCATION: The application template region.

  • SPACE: Your space ID.

  • APPLICATION_TEMPLATE: The template ID for the composite application template.

  • SHARED_TEMPLATE_URI: The standard application template or component shared template revision URI.

  • VARIABLE_NAME: The internal variable name inside the component that you want to alias.

  • ALIAS_NAME: The unique alias name to use for the template input variable.

To configure multiple aliases when creating a component, repeat the --input-variable-aliases flag, provide a JSON list, or supply a YAML or JSON file:

  • Repeat the flag: --input-variable-aliases=variable=v1,alias=a1 --input-variable-aliases=variable=v2,alias=a2

  • Provide a JSON list: --input-variable-aliases='[{"variable": "v1", "alias": "a1"}, {"variable": "v2", "alias": "a2"}]'

  • Provide a YAML or JSON file: --input-variable-aliases=path/to/aliases.yaml

For more information, see gcloud design-center spaces application-templates components create.

Update aliases on an existing component

To add an alias to an existing component in a composite template, use the --add-input-variable-aliases flag with the components update command:

gcloud design-center spaces application-templates components update \
    COMPONENT \
    --project=PROJECT \
    --location=LOCATION \
    --space=SPACE \
    --application-template=APPLICATION_TEMPLATE \
    --add-input-variable-aliases=variable=VARIABLE_NAME,alias=ALIAS_NAME

Replace the following:

  • COMPONENT: The ID for the component that you want to update.

  • PROJECT: Your management project ID.

  • LOCATION: The application template region.

  • SPACE: Your space ID.

  • APPLICATION_TEMPLATE: The template ID for the composite application template.

  • VARIABLE_NAME: The internal variable name inside the component that you want to alias.

  • ALIAS_NAME: The unique alias name to use for the template input variable.

To add multiple aliases, repeat the --add-input-variable-aliases flag, or provide a JSON list or file.

Manage existing aliases

To modify or remove aliases on an existing component, use the following commands:

  • Remove an existing alias from a component:

    gcloud design-center spaces application-templates components update \
        COMPONENT \
        --project=PROJECT \
        --location=LOCATION \
        --space=SPACE \
        --application-template=APPLICATION_TEMPLATE \
        --remove-input-variable-aliases=variable=VARIABLE_NAME,alias=ALIAS_NAME
    
  • Remove all variable aliases from a component:

    gcloud design-center spaces application-templates components update \
        COMPONENT \
        --project=PROJECT \
        --location=LOCATION \
        --space=SPACE \
        --application-template=APPLICATION_TEMPLATE \
        --clear-input-variable-aliases
    
  • Replace all existing aliases with a new list, or supply aliases in a YAML or JSON file:

    gcloud design-center spaces application-templates components update \
        COMPONENT \
        --project=PROJECT \
        --location=LOCATION \
        --space=SPACE \
        --application-template=APPLICATION_TEMPLATE \
        --input-variable-aliases=ALIASES_FILE_PATH
    

    Replace the following:

    • ALIASES_FILE_PATH: The local path to the YAML or JSON file containing your variable aliases.

    Format the YAML or JSON file with a list of variable and alias pairs. For example:

    - variable: "db_password"
      alias: "database_password"
    - variable: "project_id"
      alias: "database_project_id"
    

For more information, see gcloud design-center spaces application-templates components update.

Verify your template

Before you share your composite template with developers, deploy and verify your template in App Design Center. This step helps you verify functionality before a scaled deployment on multiple machines.

To verify your template, do the following:

  1. From the design canvas, click Continue and select Create application to deploy.

    The Create an application panel opens.

  2. In the Composite application details area, enter the application details.

    For more information, see Create an application draft.

  3. Click Next.

  4. For each building block you added to the composite template, an application will be created when you deploy. Configure each application and click Next.

    For more information, see Create an application draft.

  5. Test your deployed application to make sure that it meets your requirements.

  6. To avoid recurring costs, delete the test deployment.

Create a scaled deployment

To deploy and manage multiple instances of your composite template, use App Lifecycle Manager.

  1. Verify your template in App Design Center.

  2. From the design canvas, click Continue and select Deploy at scale with App Lifecycle Manager.

    App Lifecycle Manager opens in the Google Cloud console.

  3. To deploy in App Lifecycle Manager, see Deploy a SaaS offering.

Share your template

To make your template available to developers, you can add it to a catalog and share. When you add a template to a catalog the template is available as an application source in spaces where the catalog is shared.

To share the template, do the following:

  1. From the design canvas, click Add to Catalog.

  2. To manage spaces where the catalog is shared, see Manage catalogs.

Revise and reshare your template

As you gain experience with your application and your business needs evolve, you might want to update your template. For example, you might decide to improve performance for a backend service by adding a Memorystore service for caching.

When you modify a template, you create a template revision. To apply your changes to existing applications, developers must deploy applications using the revision.

App Design Center doesn't automatically publish template revisions to catalogs. To share the latest revision, publish the template to the catalog again.

To create a new revision, do the following:

  1. From the navigation menu, click Templates.

    Go to Templates

  2. Select the application template that you want to revise. The canvas opens.

  3. Modify the template to fit your new requirements. For example, add and configure a new component.

  4. To share the latest revision with other spaces, add the template to your catalog again.

Delete a template

If you no longer need a template, you can delete it.

Design canvas

  1. From the design canvas, click Actions.
  2. Click Delete.

gcloud CLI

Delete an application template.

```sh
gcloud design-center spaces application-templates delete APPLICATION_TEMPLATE \
--project=PROJECT \
--location=LOCATION \
--space=SPACE
```

Replace the following:

  • APPLICATION_TEMPLATE: The template ID for the application template that you want to delete.
  • PROJECT: Your management project ID.
  • LOCATION: The application template region.
  • SPACE: Your space ID.

For more information, see gcloud design-center spaces application-templates delete.

What's next