Blueprint Design

What is a Stack Automation blueprint?

A blueprint is a template for provisioning a deployment that contains references to different IaC Components ("Grains") that together define the applications, cloud infrastructure, networking and policies that make up a specific deployment. Blueprints are stored as source-controlled YAML files, and each grain in a blueprint is a reference to one IaC or automation file (for example, a Terraform module or a Helm chart) that will be deployed as part of the deployment, and the component's designated inputs, outputs and execution information.

A blueprint also contains the orchestration between the grains (provisioning order and dependencies, shared parameter storage, deployment duration policies, tag values, etc.), and when launched, deploys a whole stack, from the infrastructure layer to the application itself.

There are three ways to end up with a blueprint in Stack Automation: let Stack Automation wrap a discovered IaC asset for you behind the scenes (Option A), author a multi-grain blueprint YAML yourself in your source control repository (Option B), or build one visually using the Designer Canvas (Option C).

Option A: Let Stack Automation wrap your assets for self-service

Once a repository is connected and its assets are discovered (see Discover Your Assets), each discovered IaC asset appears in your space's Assets page. From there, you can make any asset (or an existing blueprint) available for self-service consumption with two independent toggles:

Solution Hub: makes the item visible in the Solution Hub catalog so other users in the space can launch it.
Building Block: makes the item available as a reusable component inside the visual blueprint designer (see Option C below).

Enabling either toggle on a raw IaC asset wraps it in a blueprint behind the scenes. You don't see or edit that generated blueprint's YAML directly — instead, you customize the asset's display name, icon, and labels through its own Solution Hub Design screen. If you enable the same toggles directly on a full blueprint (one created via Option B or C), you get the complete set of blueprint-level controls: Instructions, consumption Policies, Labels, and Tags, in addition to Display Name and Icon.

In your space, go to Automation > Assets and open the IaC Assets tab to see everything discovered from your connected repositories.
Toggle Solution Hub for any asset you want end-users to be able to launch from the catalog, and/or toggle Building Block for any asset you want to make reusable when building blueprints visually.
Click into the asset to open its Solution Hub Design screen, where you can set its Display Name, Category Icon, and Labels, and preview how it will appear as a catalog card.

You and your space's users can now launch deployments from these items via the Solution Hub catalog.

Option B: Create a multi-asset blueprint in your source control repository

So far, we've learned how self-service wrapping works for single-asset items. But what if you want to create an application-stack deployment? This is easily done by having multiple grains in a single blueprint or nesting an existing blueprint within a master blueprint as a grain. To create such a blueprint, you will need an IDE environment that has access to a clone of your repository, in which you can create the new blueprint's YAML file and edit it, and then commit it into your repository and push the changes to the remote repository from which Stack Automation will automatically synchronize the new blueprint.

By enforcing usage of a source control repository, each blueprint in Stack Automation will have:

A full history of tracked changes
The ability to identify which developer authored those changes
The ability to retrieve or rollback to the contents of previous versions of the blueprint file

Tips

When connecting a repository containing blueprint files to Stack Automation, it is possible to reference a branch of the repository and not its main, allowing designers the ability to test changes to blueprints before pushing them to the main/master branch and affecting the production catalog.

To create a multi-asset blueprint:

For each grain, do one of the following:
- Copy an example of that grain from a generated blueprint or from the documentation.
- Use the sample structure for that grain type in the corresponding page in The Blueprint YAML.
If grains depend on each other, add a depends-on section to the grain (in the top level, next to kind: and spec:) and provide the names of the dependent grains in a comma-separated list.
Once a grain depends on another grain, the output values from that grain can be used as values for any of the grain's inputs or attributes using the syntax {{ .grains.grain_name.outputs.output_name}}, see the examples below.
Customize the inputs and outputs sections of the blueprint to contain only the relevant inputs that the entire deployment needs, and to reflect the outputs from the grains that you would like to make available to the deployment's end-user.

Option C: Build a blueprint visually in the Designer Canvas

Beyond hand-writing YAML, Stack Automation also provides a visual, drag-and-drop way to build multi-grain blueprints: the Designer Canvas.

Mark the IaC assets you want to reuse as Building Block components first (see Option A) — only assets with this toggle enabled can be dragged onto the canvas.
Go to Automation > Assets > Blueprints and click New Blueprint.
Choose Custom Blueprint to start from a blank canvas, or pick one of the pre-built infrastructure pattern templates if your space has any configured.
Give the blueprint a name, an optional description, and a default management server (used to automatically populate every grain's agent input), then click Create.
On the Designer Canvas, click the Add Grains button to open the Building Blocks Library, then add your Building-Block-marked assets onto the canvas as grains, connect them to define dependencies, and configure each grain's inputs and outputs directly in the UI.
Switch to the Blueprint YAML tab at any time to view the underlying YAML — since this blueprint is backend-stored (not yet pushed to a repository), you can also edit the YAML directly here.
Use the blueprint's Overview, Instructions, and Policies tabs to configure its Solution Hub/Building Block visibility, end-user instructions, and consumption policies.

Removing a blueprint

As mentioned above, there are two types of blueprints, blueprints stored in Stack Automation (whether wrapped automatically via Option A or built visually via Option C) and source-controlled blueprints (stored in your repository, per Option B).

To delete a stored-in-Stack-Automation Blueprint, in the Blueprints tab, click on the Blueprint and then click the Delete button on the top right corner.
To delete a "repository" Blueprint, simply delete the blueprint file from the repository's branch that the Stack Automation space is connected to.

Example multi-grain blueprint 1: Helm Application with MySQL and S3 Deployed by Terraform

This blueprint is available in the Sample space here, which deploys 2 Terraform modules and a Helm chart:

spec_version: 2
description: Robotshop microservices application deployed on K8S with Helm and RDS deployed with TF

outputs:
  WebsiteUrl:
    kind: link
    value: 'https://stackautomation.cisco.com/static/demo-quick-links/stans-robot-shop.html'


grains:
  mySqlDB:
    kind: terraform
    spec:
      source:
        path: github.com/QualiTorque/samples.git//terraform/rds
      agent:
        name: eks-demo
      inputs:
        - sandbox_id: '{{ sandboxid | downcase }}'
        - size: small 
        - allocated_storage: 20
        - db_name: demo_db
        - engine_version: 8.0.26
        - engine: MySQL
        - username: adminuser
        - vpc_id: vpc-02e3bca90b081cd0f
        - region: us-east-1
      outputs:
        - hostname
        - connection_string

  s3Bucket:
    kind: terraform
    spec: 
      source:
        path: github.com/QualiTorque/samples.git//terraform/s3
      agent:
        name: eks-demo
      inputs:
        - region: eu-west-1
        - acl: public-read
        - name: 'robotshop-s3-{{ sandboxid | downcase }}'
      outputs:
        - s3_bucket_arn

  robotShopMicroservices:
    kind: helm
    depends-on: mySqlDB, s3Bucket
    spec:
      source:
        path: https://github.com/QualiTorque/samples.git//helm/robotshop
      agent:
        name: eks-demo
      inputs:
        - hostname: 'robotshop-{{ sandboxid | downcase }}'
        - version: 0.4.3
        - connectionString: '{{ .grains.mySqlDB.outputs.connection_string }}'
        - objectStore.s3BucketArn: '{{ .grains.s3Bucket.outputs.s3_bucket_arn }}'
        - redis.storageClassName: gp2

Example multi-grain blueprint 2: Web-game on S3 (using CloudFormation and Terraform)

spec_version: 2
description: "S3 Bucket creation with Input and Output parameters"

inputs:
   Access Control:
      type: string
      description: >
        Type of access to configure on Bucket objects: Private, PublicRead, PublicReadWrite, AuthenticatedRead,
        LogDeliveryWrite, BucketOwnerRead, BucketOwnerFullControl, or AwsExecRead
      default: "PublicRead"
      allowed-values: ["Private", "PublicRead", "PublicReadWrite"]
   Bucket Name:
      type: string
      default: my-bucket-test
   AWS Region:
      description: "The name of the AWS Region to use"
      default: "us-west-1"
      allowed-values: ["us-west-1", "us-west-2", "eu-west-1"]
    
outputs:
   S3 Bucket ARN:
        value: '{{ .grains.my-S3-Bucket.outputs.Arn }}'
   S3 Bucket Domain Name:
        value: '{{ .grains.my-S3-Bucket.outputs.DomainName }}'
        kind: link
   Webgame Link:
        value: '{{ .grains.S3-Upload-Webapp-File.outputs.website_link }}'
        kind: link

grains:
  CFN-S3-Bucket:
    kind: cloudformation
    spec: 
      source:
        store: assets
        path: assets/cfn/s3/AWSS3Bucket.yaml
      region: '{{ .inputs.["AWS Region"] }}'
      agent:
        name: demo-prod
        service-account: app-sa
      inputs:
        - AccessControl: '{{ .inputs.["Access Control"] }}'
        - BucketName: '{{ .inputs.["Bucket Name"] }}-{{ sandboxid | downcase }}'
      outputs:
         - Arn
         - DomainName
  
  S3-Upload-Webapp-File:
    kind: terraform
    depends-on: CFN-S3-Bucket
    spec:
      source:
        store: assets
        path: assets/terraform/s3-deploy-webapp
      agent:
        name: demo-prod
        service-account: app-sa
      inputs:
      - bucket_name: '{{ .inputs.["Bucket Name"] }}-{{ sandboxid | downcase }}'
      - region: '{{ .inputs.["AWS Region"] }}'
      outputs:
      - website_link

What is a Stack Automation blueprint?​

Option A: Let Stack Automation wrap your assets for self-service​

Option B: Create a multi-asset blueprint in your source control repository​

Option C: Build a blueprint visually in the Designer Canvas​

Removing a blueprint​

Example multi-grain blueprint 1: Helm Application with MySQL and S3 Deployed by Terraform​

Example multi-grain blueprint 2: Web-game on S3 (using CloudFormation and Terraform)​