Search…
Blueprints

What is a Blueprint?

A blueprint holds all the definitions needed to create ephemeral environments, including: services, dependencies and other deployment configurations.
A blueprint may also include the definition of database seeding jobs or testing tools that help the developer use the environment effectively.
Velocity's blueprints are defined using industry-standard formats: Docker Compose, Kubernetes Resources, Helm and Kustomize augmented with Velocity annotations and templates.

Basic definitions

In order to be able to converted into a working Velocity Blueprint, Kubernetes entity definitions need to be augmented with a combination of Velocity annotations and templates.
  • Velocity Annotations: These are added to your K8s entity definitions under the metadata.annotations tag. They add important information about your application, such as: an identifier, dependencies, connectivity definitions and more.
    • Velocity Annotations are located under metadata.annotations
    • Velocity Annotations use the following syntax: velocity.tech.v1/{directive}
  • Velocity Templates: These are placeholders that you add anywhere in your K8s entity definitions which will be interpreted by Velocity dynamically during provisioning. Templates are used to set dynamic values in environment variables or define unique identifiers to cloud resources and more.
    • Velocity Templates are located anywhere along your K8s resource definitions
    • Velocity Templates use the following syntax: {velocity.v1.<Property>}for global templates or {velocity.v1:<Velocity Service>.<Property>} for service-level templates.
Example:
apiVersion: apps/v1
kind: Deployment
metadata:
name: backend
# <------- START OF VELOCITY ANNOTATIONS ------->
annotations:
velocity.tech.v1/id: backend # Service Identifier
velocity.tech.v1/dependsOn: mysql # Service Dependency
# <------- END OF VELOCITY ANNOTATIONS --------->
spec:
containers:
- name: backend
env:
- name: DB_CONNECTION_STRING
# <VELOCITY_TEMPLATE that is set dynamically upon provisioning>
value: '{velocity.v1:mysql.exposures(port=mysqlport).uri}'

Velocity Services

A Velocity Service represents a standalone application or micro-service deployed in your Velocity environment. It can be comprised of a single k8s resource defintion, but most often it will be comprised of a collection of interrelated Kubernetes resource definitions, such as a deployment, k8s service, ingress, secrets and more.
Your Velocity Blueprint (i.e., your augmented k8s resource defintions or Helm Chart) defines Velocity Services, with their dependencies and required configuration.
Velocity Services are created in one of two ways:
Auto-detected Velocity Services
Kubernetes Jobs and Deployments are automatically designated as Velocity Services.
Kubernetes Jobs exist as Velocity Services independently.
Kubernetes Deployments are automatically merged with the following, related k8s resources, which are then designated together as a single Velocity Service:
  • Config Maps (specified in the Deployment's env or envFrom tags)
  • Secrets (specified in the Deployment's env or envFrom tags)
  • k8s Services (defined by the Deployment's Service selector)
  • Ingress (defined by the Deployment's Service port)
NOTE: While auto-detected services do not need a Velocity Service Identifier, they still require Velocity annotations and templates to define their various dependencies and to incorporate dynamically-generated values, such as entity names and connectivity & configuration details.
User-defined Velocity Services
You can also create Velocity Services from other first-class resource definitions by adding a Velocity Service Identifier annotation to the metadata.annotations portion of the resource definition.
For example, cloud resource CRDs (such as AWS S3 bucket, SQS and other similar resource definitions), are not standard k8s resources, but they are seen and treated as first-class entities, which means that they can be designated as Velocity Services with the addition of a Velocity Service Identifier.
User-defined Velocity Services, like auto-detected Velocity Services, will likely require additional Velocity Annotations and Templates to incorporate dynamically-generated values and connectivity & configuration details.

Velocity service identifier

User-defined Velocity Services require a Velocity Service Identifier.
The Velocity Service Identifier sets the name of the service in Velocity, and allows other Velocity Services to reference it, along with any values defined within it, such as ports and entity names, for example.
The identifier is set on the Kubernetes resource's metadata.annotations using the following annotation format: velocity.tech.v1/id: {value}.
For example:
apiVersion: storage.cnrm.cloud.google.com/v1beta1
kind: StorageBucket
metadata:
annotations:
velocity.tech.v1/id: bucket

Dependencies

In Velocity, you can define dependencies between Velocity Services.
Dependencies are used to build a dependency-map that helps provision the environment correctly.
Common use cases for dependencies:
  1. 1.
    Provisioning order: Velocity uses dependencies to determine the optimal provisioning order.
  2. 2.
    Environment completeness: When a new environment is created, Velocity ensures that services have all the necessary dependencies ready.
  3. 3.
    Connectivity and configuration: Velocity allows you to set connection strings and other environment variables dynamically using properties from the service dependencies.
The dependencies are defined by adding velocity.tech.v1/dependsOn with a comma-separated list of velocity identifiers (defined by the velocity.tech.v1/id annotation) of the dependent services.
For example:
apiVersion: apps/v1
kind: Deployment
metadata:
name: backend-deployment
annotations:
velocity.tech.v1/id: backend
velocity.tech.v1/dependsOn: mysql, postgres # Dependency
--
apiVersion: apps/v1
kind: Deployment
metadata:
name: mysql
annotations:
velocity.tech.v1/id: mysql
--
apiVersion: apps/v1
kind: Deployment
metadata:
name: postgres
annotations:
velocity.tech.v1/id: postgres
Copy link
On this page
What is a Blueprint?
Basic definitions
Velocity Services
Velocity service identifier
Dependencies